Setting Up to Use ThingWorx Software Content Management (SCM) with EMS Devices
There are several steps to setting up the EMS, LSR, Thing Templates, Things, and security to be able to use the Software Content Management (SCM) extension for ThingWorx Asset Advisor with your EMS and LSR devices. For each step listed below, click the title to display the content; click it again to hide the content:
Step 1. For Assets Running EMS and LSR: Configure the EMS and LSR to Support SCM
Follow these steps to configure your EMS and LSR to support SCM:
1. On the devices running the EMS or LSR, you must create the following directories in the path, C:\microserver\edge (Windows) or /microserver/edge (Linux):
◦ in
◦ out
◦ updates
◦ staging
2. By default the EMS and LSR do not have permissions to write to these directories. Make sure that both the EMS and LSR can write to these directories by granting the appropriate Windows permissions to them. If you are using the EMS and LSR on Linux devices, make sure that you grant the appropriate permissions to the EMS and LSR.
3. Modify the <ems_home>\etc\config.lua file to include each device using the following syntax:
scripts.AssetName = {
file = "thing.lua",
template = "example",
sw_update_dir = "C:\\microserver\\edge\\updates\\" }
Make sure the updates directory at the path specified (C:\microserver\edge).
4. Modify the file, <ems_home>\etc\config.json, as follows:
b. Add a file object:
"file": {
"buffer_size": 32400,
"virtual_dirs": [{
"in": "C:\\microserver\\edge\\in"
}, {
"out": "C:\\microserver\\edge\\out"
}, {
"updates": "C:\\microserver\\edge\\updates"
}],
"staging_dir": "C:\\microserver\\edge\\staging"
}
 | Make sure the directories defined above, namelyin, out, updates, and staging, exist at the path <ems_home>\edge. |
c. Remove any reference to auto_bind devices tthat are connected via LSR.
d. Make sure that the updates directory listed in <ems_home>\etc\config.json is the same as the one listed in <ems_home>\etc\config.lua.
5. Modify the <ems_home>\etc\config.lua file to include each device using the following syntax:
scripts.AssetName = {
file = "thing.lua",
template = "example",
sw_update_dir = "C:\\microserver\\edge\\updates\\"
}
| | Make sure that the updates directory exits at the path, C:\microserver\edge |
6. In the template file specified in <ems_home\etc\config.lua, add the following at the very top of the file:
require "shapes.swupdate"
| | You must place this line at the very top, above the module statements, for it to work. |
Next, create Thing Templates for EMS and LSR devices that you want to be visible in ThingWorx Asset Advisor so that you can use ThingWorx Software Content Management.
Step 2. From ThingWorx Composer: Set Up Thing Templates for EMS and LSR Devices to be Available in ThingWorx Asset Advisor
For devices running the EMS or LSR to be available in the ThingWorx Asset Advisor, you need to set up Thing Templates for the types of devices. These Thing Templates must implement the following Thing Shapes:
• PTC.Factory.PhysicalAssetThingShape
• PTC.SCA.SCO.AssetIdentifierThingShape
• PTC.SCA.SCO.StatusThingShape
• PTC.ISA95.IdentifierThingShape
• PTC.SCA.SCO.MonitoredPropertiesThingShape
For complete details, refer to Creating Custom Thing Templates for Equipment Types in the ThingWorx Apps Help Center.
Next, create and configure EMS and LSR Things to use in Asset Advisor with ThingWorx Software Content Management (SCM).
Step 3. From ThingWorx Composer: Create and Configure EMS/LSR Things for Use in Software Content Management (SCM)
For EMS/LSR Things to be available in the SCM module of Asset Advisor, follow these steps;
1. In ThingWorx Composer, create the Things to represent your EMS and LSR devices using the Thing Templates created in Step 2. Make sure that each Thing has a name that matches a name in the config.lua file.
2. Navigate to a Thing.
3. On the General Information page, add the following Implemented Shapes:
◦ PTC.Asset.ManagedAsset
◦ TW.RSM.SFW.ThingShape.Updateable
◦ PTC.Resource.Asset.SCMResourceThingShape
4. Add PTC:AssetType to Tags.
5. Click Save.
Next, create the security entities and grant the appropriate visibility and permissions required for SCM. Make sure that the SCM Extension has been imported into your ThingWorx Platform first. For instructions, refer to Importing Extensions in the ThingWorx Platform Help Center.
Step 3. From Composer: Create Security Entities and Grant Visibility and Permissions for SCM
As long as the ThingWorx Software Content Management (SCM) Extension has been imported into your ThingWorx Platform, follow these steps to set up the required permissions for using SCM with EMS devices:
1. Create a new Organization. For example, SCMEdgeDevicesOrg.
2. Create a new User Group. For example, SCMEdgeDevicesGroup.
3. Add the SCMEdgeDevicesGroup to the SCMEdgeDevicesOrg.
4. Add the SCMEdgeDevicesGroup as a member of the TW.RSM.RemoteAssets User Group.
5. Add the SCMEdgeDevicesOrg to the Visibility permissions of the following things:
a. TW.RSM.SFW.SoftwareManager Thing
b. TW.RSM.SFW.SoftwareManager.DeliveryTarget Thing
c. TW.RSM.SFW.SoftwareManager.Campaign Thing
d. TW.RSM.SFW.SoftwareManager.Definition Thing
6. Add an override, giving the Service Invoke permission to SCMEdgeDevicesGroup on the GetDataTableEntryByKey service of the TW.RSM.SFW.SoftwareManager.DeliveryTarget Thing.
7. Add an override, giving the Service Invoke permission to SCMEdgeDevicesGroup on the following services of TW.RSM.SFW.SoftwareManager Thing:
a. UpdateState
b. CompleteDeliveryTarget
c. StartDownload
8. Assuming that you created a non-admin user for the EMS application key, add that non-admin user to the TW.RSM.EdgeDevices user group. Using the example in Create an Application Key for EMS, add the wsemsUser to the TW.RSM.EdgeDevices user group.
Step 4. Using SCM
Assuming you have started or restarted the EMS and LSR, follow these steps to use SCM:
1. In SCM, create a new package, using the following settings:
◦ Selected Content Zip File Name — The name of the zip file with the lua file in it.
◦ Instruction File Name in Zip File — The name of the lua file contained in the zip file.
2. Create a test deployment for the new package:
a. Verify that the remote device is properly connected to ThingWorx before deploying a package.
b. Use New Asset Search to create a new saved search for just the devices specified in the config.lua file.
c. Select the saved search in the Included Assets section, and click the plus icon to add it to the list.
d. Select the Confirm checkbox, and then click the Deploy button.
3. In the LSR, updates about the script should appear as output. Note the following:
◦ Output does not appear if the LSR is running as a service.
◦ Any errors in running the lua file are written to the Windows Event Logs.
◦ To troubleshoot, run the LSR in a console window instead of as a service..
4. In SCM, the status should update from started to either completed or failed. In ThingWorx Utilities versions prior to 7.4, errors may prevent status updates. This issue was fixed in v.7.4. If the package download stalls without completing, refer to KCS Article CS248122..
For More Information
For information on ThingWorx Apps setup for SCM, refer to the Software Content Management topic in the ThingWorx Apps 8.5 Help Center.
For details on creating and deploying packages using the UI of the ThingWorx SCM Extension, refer to the ThingWorx Utilities Help Center.