Setting Up SCM
To set up a ThingWorx .NET SDK edge application to support the SCM Extension for ThingWorx Platform, you need to add the ThingWorx SCM Edge Extension to your application. The steps to set up your environment for SCM follow:
1. If you are currently using ThingWorx Utilities and have not read the release notes, see the
ThingWorx
Utilities Packaging Notice. Otherwise, continue to the next step. To use the SCM Edge Extension in your application and ThingWorx Platform, you need the ThingWorx Utilities Core package and the separate ThingWorx SCM Extension package.
2. Check that your environment meets the requirements specified in
Before You Begin.
ThingWorx Utilities Packaging Notice
For release 8.3.0, ThingWorx Utilities was repackaged and made available as the following separate extensions:
• ThingWorx Utilities Core
|
This extension bundle is a pre-requisite for the other extensions and must be installed first.
ThingWorx Asset Manager and ThingWorx Alert Manager are being improved and migrated to ThingWorx Asset Advisor. For release 8.3.0, however, the ThingWorx Utilities Core bundle includes both of them.
|
• ThingWorx Audit Manager
• ThingWorx Software Content Management (SCM)
• ThingWorx Workflow Manager
|
If you are installing both Audit Manager and SCM, the extension that is imported second reports the following warnings:
Extension TWX_Converge_RSM_Core_ExtensionPackage:8.3.0 skipped because it is already installed.
Extension TWX_Converge_RSM_FileTransfer_ExtensionPackage:8.3.0 skipped because it is already installed.
You can ignore these warnings.
|
Before You Begin
This topic assumes you have the following set up.
• A ThingWorx Platform instance (v. 8.3.0 or later) is installed and running.
• The latest .NET SDK and C SDK are installed on your machine (the installation program for the .NET SDK does this automatically).
• The following supporting software installed on your machine:
◦ Microsoft Visual Studio (Windows) 2017 or later.
◦ .NET Framework, v.4.5.2 or later.
◦ Curl.
|
For Windows users, be sure that any necessary build tools have been added to your PATH.
|
• You have downloaded the following software from the PTC Support site:
Obtaining and Importing the ThingWorx Utilities Extensions
The ThingWorx Utilities packages that you need to run the SCM on your ThingWorx platform are available for download on the
ThingWorx Platform page of the PTC Support site. Select the version of ThingWorx Platform that you are running. For example,
Release 8.5. Then expand
Most Recent Version. Continuing with the 8.5 release as our example, download
ThingWorx-Utilities-Core-8-5-0 and
ThingWorx-Utilities-Software-Content-Management-8-5-0. For instructions on importing extensions, refer to the topic,
Importing Extensions in the ThingWorx Help Center.
Verify the Import
To verify that the extension has been successfully imported, complete the following steps:
1. In ThingWorx Composer, search for and select the PTC.ConvergeConsole mashup.
2. Click View Mashup.
3. On the ThingWorx Utilities Console, click the tile and verify that it loads the mashup for the extension package that you have installed.
Setting Up Things to Use SCM
For you to be able to see your devices in the user interface of Asset Advisor for SCM, the Things that represent your devices on the ThingWorx Platform need to be configured as follows:
1. Log in to ThingWorx Composer as a user who can edit the Things for your devices.
2. Navigate to a Thing, and on the General Information page, select TW.RSM.Template.AssetWithTunnelsAndFileTransfer as the Thing Template that the Thing implements.
3. Add the following Implemented Shapes PTC.Asset.ManagedAsset, TW.RSM.SFW.ThingShape.Updateable, and PTC.Resource.Asset.SCMResourceThingShape.
4. Add PTC:AssetType to Tags.
5. Click Save.
6. Repeat these steps for each Thing to which you want to be able to send file-based packages.
Also in ThingWorx Composer, make sure you grant visibility and permissions for the Things and add users to user groups and grant them the permissions and visibility needed for SCM. See
Entity Permissions in the ThingWorx Help Center on the PTC Support site.
If you plan to use ThingWorx Asset Advisor with the ThingWorx SCM Extension for a user interface, make sure that you follow the instructions in the
ThingWorx Apps 8.5 Help Center to set up Asset Advisor to display the SCM tile and to grant visibility and permissions to users.
Although it is deprecated, you can use ThingWorx Utilities v.8.5 with the ThingWorx SCM Extension user interface. Be sure to follow the instructions in the topic,
"Visibility Support for ThingWorx Utilities", in the ThingWorx Utilities Help Center to grant visibility and permissions for SCM to end users. For users, refer to
Setting the TWXLIB Environment Variable for Extension Library Loading (optional)
On a Windows machine, the installer creates a registry entry, which is HKEY_LOCAL_MACHINE/Software/Wow6432Node/ThingWorx/scmext/extPath. You can also set the TWXLIB key in the registry, under the registry key created by the installer. That way, you do not need to set this environment variable for the extension library. Here is an example of the registry key that the installer creates:
The TWXLIB environment variable provides a pointer to the location from which the .NET SDK can load the extension libraries. The directory in which your scmext library is generated on a Windows platform is C:\Program Files\tw-c-sdk\ext\scmext.dll. Since the default TWXLIB value of the example application is a relative path, adjust your TWXLIB variable if you want to execute from a path different from the one listed above. For example:
set TWXLIB C:\path\to\directory\containing\scmext
Make sure that you refresh your environment after setting the variable and before trying to run the application again.
Run the Examples
Run the SCM Examples, following the instructions in the following topics:
SCMThing Extends the FileTransferVirtualThing
As of v.1.0.1 of the SCM Edge Extension for .NET and v.5.8.2 of the .NET SDK, the ScmThing extends the FileTransferVirtualThing, allowing file transfers to and from the SCM asset as well as SCM deployments. Constructors for the ScmThing have been added to support FileTransferVirtualThing. The following constructors are acceptable:
public ScmThing(string name, string description, string identifier, ConnectedThingClient client)
public ScmThing(string name, string description, string identifier, ConnectedThingClient client, string rebootSurvivalFilePath,string rebootSurvivalFileName,bool rebootSurvivalEnabled,string rebootWarningFile)
public ScmThing(string name, string description, ConnectedThingClient client)
In addition, an identifier can be null for any constructor. While this change occurred in the .NET SDK itself, it is noted here in case you want to use an identifier in your SCMThing constructor.
| You cannot add virtual directories as part of ScmThing construction as you can for FileTransferVirtualThing because the virtual directories are overwritten as a result of the setup sequence. To add your own virtual directories, use AddVirtualDirectory() after the construction of the ScmThing. |
Troubleshoot Common Issues
The extension library failed to load.
This error is common if you are trying to run the example from an unusual directory. Set the TWXLIB environment variable to the proper directory containing the scmext library by opening a new Command Prompt to reload your environment variables and then running the following command:
set TWXLIB="/path/to/directory/containing/my/scmext/library"
If TWXLIB appears to be set properly, but the .NET SDK or C SDK cannot be loaded by .NET SCM, make sure that your installed SDK build configurations (Release/Debug) match that of the .NET SCM project.
If you encounter heap space memory corruption and/or crash during or after loading the SCM extension, make sure that your installed .NET SDK build configuration (Release/Debug) matches that of the SCM project.
The examples may not have the correct reference to the .NET SDK. If this is the case, delete the current reference and manually add a reference to the thingworx-dotnet-common.dll back in to build.