Manage Licensing with Foundation Subsystems Part 1

[#1]

• Guide Concept
• Step 1: Introduction
• Step 2: Get User Count
• Step 3: Get Current License Info
• Step 4: Create Dashboard Mashup

Use Subsystems to retrieve User/Thing-count and License-expiration information

Guide Concept

In this guide, you'll learn how a Foundation Administrator can access important license-accounting Subsystems. 

In particular, we'll look at the User Management and Licensing Subsystems, and how you can use them to ensure that you're not getting close to running out of Users, Things, or your time-to-expiration. 

We'll also explore how you can import a new license_capability_response.bin file when your original license is running low on time. 

You'll learn how to

• Access the Foundation Subsystems
• Execute built-in Services to retrieve:
  • User counts
  • Thing counts
  • License expiration count
• Create a "License Dashboard" Mashup
• Update to a new License

NOTE: The estimated time to complete ALL parts of this guide is 30 minutes

Step 1: Introduction

ThingWorx Foundation uses a licensing system based around a file named license_capability_response.bin.  However, if you're using the downloadable installer, then it's possible that you've never even touched this part of the system before.

Besides doing the initial install, you'll also have to check to see that your license has enough Users, Things, and time left before expiration. You need to ensure that a new license is acquired and properly replaced beforehand... or else your Foundation installation may become unusable. 

Therefore, this guide will run you through how to access that information, as well as how to update to a new license_capability_response.bin file when the time is right. 

Step 2: Get User Count

The first item we'll investigate is checking on our number of Foundation Users. 

When first developing an IoT application, low User counts are typically the norm. Only your team really needs access to Foundation itself, so having only a few Users more than your R&D-team-size is possibly going to be sufficient. 

And, if your application is something along the lines of factory-monitoring, then it's possible that your User counts, even when deployed, are going to continue to stay relatively low. 

However, many IoT applications involve a tremendous number of Users, as your end-customers will generate a Foundation User whenever they sign up for your application. Think something along the lines of a ride-sharing app, or even a Smart Cities play... either of those can result in thousands (if not tens-of-thousands) of Users. 

As such, a Foundation system administrator will need to keep a tight track on the User counts to ensure, whenever you're approaching your upper threshold, that enough warning is given to provide time to receive and install a new license_capability_response.bin with a larger User count. 

1. Navigate to Foundation Composer's Browse > All.
   
   
   
2. On the left-side Navigation, scroll down until you see the System section.
   • Note that you will likely be unable to even see the System section unless you are an Administration-level User.
     
     
   
3. Click Subsystems.
   
   
   
4. Click UserManagementSubsystem.
   
   
   
5. At the top, click Services.
   
   
   
6. Scroll down and find the built-in GetUserCount Service.
   
   
   
7. On the line for GetUserCount, click the "play" icon for Execute Service.
   
   
   
8. At the bottom-right of the pop-up, click Execute.
   
   
   
9. Click Done to close the pop-up.
   
   

The return value from GetUserCount is one way to reveal how many current Users are provisioned for your Foundation system. 

Moving forward, we'll explore yet another way, while also looking into our Thing counts. 

In particular, you might find that the GetUserCount value doesn't completely match due to some internal system accounts. These system accounts are not counted against your license, however, and may need to be accounted for when using the GetUserCount Service. 

Step 3: Get Current License Info

While GetUserCounts can be helpful for getting the current amount of provisioned Users, it does nothing to compare that count to the total allowed by the license. 

Instead, we'll make use of a different Subsystem, i.e. the LicensingSubsystem. 

1. Return to Browse > System > Subsystems.
   
   
   
2. Click LicensingSubsystem.
   
   
   
3. At the top, click Services.
   
   
   
4. Scroll down until you find GetCurrentLicenseInfo.
   
   
   
5. On the GetCurrentLicenseInfo line, click the "play" icon for Execute Service.
   
   
   
6. On the bottom-right of the pop-up, click Execute.
   
   
   
7. When you're done analyzing the counts, click Done to close the pop-up.

The first thing to notice is that the InUseFeatureCount for twx_named_user possibly does not match the return of GetUserCount. As already mentioned, this is because of system accounts that are not counted against your license. 

For example, for a fresh installation, the GetUserCount may return 4, while InUseFeatureCount returns 2. The 2-count is more accurate, as it is used versus your total license-amount. However, GetCurrentLicenseInfo is less useful for doing a simple comparison between a stored "last user amount" vs "current user amount". 

The solution is simple. Compare the return of GetUserCount versus the return of GetCurrentLicenseInfo to determine the true total. In this case, the number of system accounts is 2, so some "GetUserCount - 2" custom-Service could be very helpful.

In addition, GetCurrentLicenseInfo returns the very important twx_things value, i.e. how many Thing Entities have been created in the system. This is typically another hard limit in your license, and needs to be watched over. 

Finally, the DaysRemaining column shows how long you have before your license becomes inactive. This is something which needs to be constantly monitored to ensure that your Foundation system as a whole is still running!

Next, we'll explore making a Mashup to reference these built-in Services in a more comfortable environment which auto-updates and can be used as, effectively, a Foundation system dashboard.

Step 4: Create Dashboard Mashup

While the User Management and Licensing Subsystems can be used as previously described to determine relevant admin information, traversing through the Foundation backend can be tedious. 

To make User, Thing, and License Expiration Date counts easier to monitor, we'll now create a "dashboard" which automatically pulls this information into a convenient Mashup. 

1. Navigate to Browse > Visualization > Mashups.
   
   
   
    
2. Click + New. 
   
   
   
3. Leave the defaults and click OK.
   
   
   
4. In the Name field, type Licensing_Mashup.
   
   
   
5. If Project is not set, search for and select PTCDefaultProject.
6. Click Save.
7. Click Design.
   
   
   

Set Layout

Now that we have a new Mashup, we'll start adding the items we'll need to display information from the Subsystems. 

First, we'll change the Layout.

1. In the top-left, ensure that the Layout tab is active.
   
   
   
2. Click Add Top.
   
   
   
3. Ensure the new top section is selected, and set Positioning to Static.
   
   
   
4. Scroll down in the Layout tab, and set Container Size to Fixed Size.
   
   
   
5. In the new Height field, type 100, and then hit your keyboard's Tab key to lock-in your change.
   • Note that the px will be automatically added after hitting the Tab key.
     
     
   
6. At the top, click Save.

 

Add Widgets

Now that we have the Layout we want, we can add Widgets to display data coming from the backend.

1. In the top-left, click the Widgets tab.
   
   
   
2. Drag-and-drop a Label Widget onto the top section.
   
   
   
3. With the Label still selected, in the bottom-left Properties section, change LabelText to User Count, and hit Tab.
   
   
   
4. Drag-and-drop a Text Field Widget, also in the top section, and below the Label.
   
   
   
5. In the top-left Widgets tab, change Category to Legacy.
6. Drag-and-drop an Auto Refresh Widget in the top section as well. 
   
   
   
7. In the top-left Widgets tab, change Category back to Standard.
8. Drag-and-drop a Grid Advanced Widget onto the Bottom section.
   
   
   
9. At the top, click Save.
   
   

Click here to view Part 2 of this guide.