Bamboo Web License Manager Use Case and FAQs

As a software company, we're always striving to improve our products at Bamboo. In this article, I will go over improvements that we have made in our License Manager Application. With these improvements, our goal is to both make the License Manager Application easier to use, and to provide a better end user experience.

What is the License Manager Application?

For those of you who have not used Bamboo products before, License Manager Application is a utility that is shipped along with our products which provides customers with a mechanism to activate and manage licenses associated with a given product.

Why do we need to improve our License Manager Application?

Over time, all software needs updating. Updates may be made to fix a bug, to handle OS changes, and sometimes to add new functionality which will enhance the user experience. Eventually in the software lifecycle, we reach a point where continued patch updates frankly don't make much sense anymore. At this juncture, Engineering takes a bold step and proposes an overhaul to the software. With License Manager Application, we had reached that juncture.

There are three main areas which were in need of substantial overhaul in the existing LM Application. They can be categorized as follows:

1. Deployment
2. License management
3. Usability

Deployment:

The existing LM Application utility was a desktop application which was packaged as an msi installation file.  Microsoft Windows Installer Package (.msi) has been around for a while now, helping people to install desktop software with ease.  Because LM was a desktop application, it had to be installed on each SharePoint Web Front-End (WFE) server before we could activate a product. And for very same reason (i.e., because it was a desktop application) we needed to insure that it installed properly on 32-bit machines as well as 64-bits. As our customer base gets larger and larger, Support is getting many more calls related to its installation.

To address this problem, we converted LM Application from a desktop- to a Web-based application and packaged it as a SharePoint solution deployment package (wsp). The immediate benefit of this change is that it can now be deployed and managed from one centralized location (SharePoint Central Administration). This will not only provide a better end user experience, but will also provide the added benefit of helping to reduce Support calls.

Figure 1: Desktop LM vs Web LM (WLM)

License management:

The second area regards how we managed license-related files. The first issue is the files themselves. In the existing LM, licensing files were under a common files folder at a file system level (%programfiles%\commonfiles\Bamboo.Shared\license). Oftentimes, LM users did not have enough permission to create the activation file required to use a product after trial expiration. This failure eventually would often result in a Support call and a tedious troubleshooting process.

The second issue had to do with how license activation is bound to a server. In the existing version of LM, computer hardware profile is used to generate a unique code to bind the activation. Occasionally, minor hardware or software changes would result in a difference which is greater than the set tolerance, thus breaking the activation.

The third issue was manageability. Since activations are file-based and located on each WFE servers, there was no simple way to manage them from a central location.

It was pretty clear that in order to address these issues, the activation files needed to be stored somewhere other than the file system. Fortunately, SharePoint has a cool feature known as Property Bag. This feature allows developers to store and retrieve proprietary information from SharePoint database. We decided to use this feature to store all licensing-related information. This change will allow us to easily store and manage all activations through one central location.

And last but not least, instead of the hardware profile, we decided to use the SharePoint Front-End server ID as the binding code. Why?  Because the Server ID remains constant for the life of the server and will remain unaffected by hardware or software changes.

Usability:

Usability refers to the user interface of the LM application.  Though the existing UI was simple and straightforward to use, we would occasionally encounter customers having trouble using it. For example, during activation, the user first needed to locate the product assembly (Exe or DLL file) and then apply an unlock key to activate. Nothing could be simpler than this. However, the main shortcoming of the existing UI, and the one which resulted in a Support call was due to the disconnect between product name and assembly name. For example, a user buys Calendar Plus, but during activation needs to search for "Bamboo.CalendarViewExtended.dll" in order to activate the product. As you might imagine, this can get confusing, especially if a customer has multiple products installed, as many assembly names look similar.

To overcome this issue, we will now register our product in SharePoint during installation. The new Web-based user interface will display the product name so a user can select and activate without searching for assemblies.

Figure 2: No more Browse to find a product to activate

Figure 3: Simple click and activate

In the following sections I will use new WLM, going over the installation process, how to check license status, how to activate, and how the upgrade will work.

Installation

Here I have shown a sample installation Setup with Web LM. WLM is packaged as a wsp solution just as any other Bamboo product. After installation is complete, WLM will be accessible from the SharePoint Central Administration website. No more msi to run on each Front-end, and no more worrying about 32-bit or 64-bit version.

Figure 4: Link to WLM in SharePoint Central Admin under Operation tab.

Walkthrough

Simple scenario:

What follows is a quick walk-through with WLM to activate a product. As you will see, the overall process is much simpler than before.

Begin by browsing to the WLM page in SharePoint Central Administration and select the desired product. This will take you to the Product Status page where the current license status is displayed. Clicking the status will take you to the activation page where key must be entered, and the license is then activated. I have used screen shots to walk through the process step by step.

Start by clicking "Bamboo Web License Manager" in SharePoint Central Administration.

Step 1: Select product to view status.

 Figure 5: List of installed products in SharePoint (desktop products do not appear here).

Figure 6: Once on Product page, use context menu or click the product to view license status.

Step 2: Review status. Click "Expired" to begin activate process.

Figure 7: Selected product license status from all front-end servers will be listed here.

Step 3: Select server, enter unlock serial key and click Activate button to activate.

Figure 8: Activation user interface and option to activate by email (or phone).

Step 4: Review the status after activation. Proceed to activate product on other servers. (In this example, only one server is used)

Figure 9: User interface after completing the activation.

At this point, the product is properly licensed and ready for use.

Note:  The license could be moved to another server by simply deactivating it on one, and then activating it on the other server.

Advanced Scenario:

In this section we will go over steps to activate a bundle product (aka suites and packs). Other bundles such as Ultimates suites, Admin suites etc, are processed in the same manner.

Figure 10: Bundle setup.hta with WLM. Top right link is a new single click install bundle pack.

The installation process is similar to any other product. Except once the bundle package is installed it will appear under a separate bar in WLM as shown in figure 10.

Figure 11: Bundle product in WLM. Displaying packs and individual products under a separate bar.

Step 1: Click "Chart Plus Revolution Pack" link or product link (i.e., Chart Plus Web Part) to view the license status.

Figure 12: Checking license status. Click pack or individual product to check license status.

Chart Plus Revolution Pack is "Not Active" and individual products are running under "trial" license.

Figure 13: Bundle is "Not Active"

Figure 14: Chart Plus Web Part (a product in a bundle) is running under "trial" on both WFEs.

Step 2: Activate bundle by selecting a server and applying a key. One key per server is needed.

Figure 15: Activating a bundle.

Figure 16: Activation is successful on one WFE.

After activating the bundle, let's check status for an individual product.

Figure 17: Chart Plus Web Part (a product in a bundle) is running under "Enterprise" on one WFE and "Trial" license under the second WFE.

Step 3: Activate bundle on second WFE.

Figure 18: Activating bundle license on second WFE.

Figure 19: Bundle status on all WFEs.

Figure 20: License status on Chart Plus Web Part (a product in a bundle). Note that it is running under "Enterprise Licensing Scheme," i.e., bundle license across all WFEs.

Activation by E-mail (or phone):

SharePoint servers often run as a intranet without Internet connection. In scenarios like these, WLM has a provision to activate a product through e-mail or via phone.

The process is similar to online activation. User enters the key and ticks the "Activate by E-mail" option before hitting the Activate button.

Figure 21: Preparing to activate by e-mail

Activate button will show the following page where user will exchange information with Support to get an activation code.

Figure 22: Activation by E-mail form where unlock code is entered

Choosing License Server(s):

Often time SharePoint farm will have search server, database server and other servers that will show up in Farm Topology. But only few - in my case only two - are real WFE servers. To aviod confusion during activation we provided a nice little feature that let user pick upfront the WFE servers. So only pre-selected servers will be displayed during license activation process or when we check license statuses.

Figure 23: Farm topology through SharePoint Central Administration.

Figure 24:  To pre-select WFE servers start by clicking "Choose License Server(s)" link in WLM main page.

Figure 25: Uncheck all WFEs that will not deliver contents to end users.

Upgrades:

Upgrades are very crucial for us as our licensing framework went through significant changes in this release. In this section, we will look into different upgrade scenarios that may occur with our existing customers and how the changes may impact them.

There are many changes that went into the new licensing framework, but two in particular stand out. First, and most crucially, we changed the way we save and retrieve licensing information. Second, we introduced a new concept of "Product Registration" which will eliminate the need to find the assembly before activation in the Web License Manager (WLM).

As discussed earlier, to move away from file-based system, we will be taking advantage of SharePoint's property bag to store license-related information. This is a major change and will affect older products.

About "Product Registration"

"Product Registration" takes place during product deployment (wsp deployment). Product related information (name, description, licensing component etc) is recorded in SharePoint which will be used by WLM to display installed products (figure 2 and 8 show lists of installed products). This feature will benefit us in couple of ways. We can view all deployed Bamboo Web Parts and SharePoint products in one location as well as enabling activation without browsing the folders or global assembly cache.

Why this is so important?

We have quite a large customer base. While we are making enhancements to improve usability, we want to ensure that by doing so we won't break licensing for existing customers. So under this section we will go over some common upgrade scenarios and answer some potential questions which may arise as a result of these upgrades.

The following table shows some common upgrade paths available to end users.

 Figure 26 is a snapshot of a system where few products are deployed and activated on two WFE servers. The important thing to note is that the activation files are stored under the BambooShared/License folder in a file system.

Figure 26: Bamboo List Search and Chart Revolution Bundle are installed on two servers (WFEs). On the right side, both activation files are sitting in the BambooShared/License folder. The left side shows two WFEs in a SharePoint farm.

Walkthrough upgrade scenario #1:

Customer has been running Bamboo List Search (which is using licensing 2.4) for a while. Bamboo Solutions has published a new patch release on the Storefront which has been upgraded to licensing 2.5 framework. The new patch release has a bug fix which is important for the customer. Support recommended the customer get the latest version.

This is a typical scenario, and since the licensing framework has changed, there are a few questions which come to mind immediately:

Q1. Will the old activation continue to work, or do I have to reactivate?

A. Good news! You don't need to reactivate. The new licensing framework was designed with backward compatibility in mind. So any product that was activated using LM 2.7 (or even older LMs) will continue to work.

Q2. Do I need to install Web License Manager?

A. You don't need to install WLM just to use the upgraded product, but you will need it to manage the license later.

Q4. Can I still use LM 2.7?

A. LM 2.7 supports the old framework and will not work with the latest release. If you'd prefer to use desktop LM, we will have LM 2.8 that will support new and old products.

Q5. If I install the latest WLM, can I manage my licenses on all WFEs for that product?

A. Yes. You will be able to manage licenses through WLM. During the upgrade install all the activation files are copied to SharePoint so users can interact with them from the SharePoint Central Admin page.

Figure 27: After upgrade, older activation files are moved to SharePoint so license status can be displayed in WLM.

Walkthrough upgrade scenario #2:

This scenario is similar to #1 except that the product went through major changes and Bamboo decides to raise the price of the product so no one can get a free upgrade. Internally this is done through generating new unlock keys and special upgrade keys for returning customers.  In this particular scenario, the product should not work after the upgrade. The licensing framework will support this behavior as before. The customer will be required to reactivate the product using WLM and a new unlock key.

Walkthrough upgrade scenario #3 & 4:

Customer is running Bamboo PDF conversion (Windows Service) or Bamboo SharePoint Desktop Explorer (desktop application) and wishes to upgrade. Again we have a similar situation as in #1 and #2, except that this is a desktop or Windows service running on a single machine. Overall system will behave the same way as in #1 (old activation will work) and #2 (old activation will break). And since these are not Web applications, we will not use WLM.  Instead we will use LM 2.8 to activate.

Walkthrough upgrade scenario #4...8:

Upgrading bundles can get complicated. First let's look at a simpler scenario. Customer is running a bundle X with licensing v2.4 which includes product A and B.

Situation 1: Customer wants to install patch release of product A to get a bug fix. New patch release has been upgraded to licensing framework v2.5.

Q1. Will the old bundle activation continue to work for this product?

A. Currently, single product upgrade will not work out-of-the-box with old bundle activation due to assembly mismatch (bundle needing licensing 2.4 while upgraded product running on 2.5 framework).  However, by manually adding assembly redirection the old bundle activation will continue to work (not recommended though since it will effect all the products).

Q2. Can I manage the upgraded product from WLM?

A. The product will appear in WLM product page and will be managed like any other non-bundle product.

Situation 2: Customer gets upgraded Bundle with Product A and B, i.e., new release with licensing 2.5 support.

Q1. What will be the upgrade process?

A. Customer has to deploy new bundle upgrade which will install all the products in the bundle. See figure 7.

Q2. What will happen when only bundle assembly gets upgraded?

A. We don't currently support this option.

Q3. What will happened when everything get upgraded?

A. New bundle packaging - one click will deploy all products in the bundle. If user has an old activation, then that will continue to work. Otherwise, the bundle needs to be activated.

Situation 3: Existing bundle consists of Web Parts and Windows service product (some bundle with Bamboo PDF conversion) - customer wants to upgrade Windows Service product.

Q1. Will my upgraded Bamboo PDF conversion continue to work with old "bundle" activation?

A. This is similar to situation 1 above and the same will apply here too.

Situation 4: Existing bundle has Product A, B and C. A new release comes out with one or a few new products. (i.e., similar to Custom Column Packs, or the Ultimate suite).

Q1. What is the upgrade path?

A. It will work the same as today. User has two options: 1) Install and activate new products individually in the bundle, or 2) Rerun the new bundle to get everything including latest bundle licensing.

Troubleshooting:

In this section I will go over some issues that users may encounter while using WLM.

Customer may ask the following questions:

Q. I upgraded the product, WLM shows status "Active" on one server and "Not Active" on the other. I know for sure that I have active copies on both servers.

This is one problem that we anticipate hearing from customers more frequently. During the deployment, we create SharePoint custom timer jobs which are responsible to run on each server and port license activation to SharePoint. Sometimes these jobs don't execute in a timely fashion and create the above mentioned problem. Just restart the timer service on the affected server and it should resolve the problem.

Q. Are there any log files?

A. Yes, WLM uses Bamboo.Logging framework. The log files can be found in {win_temp} folder. Solution deployment creates its own log file which could be found under {installing_user_temp} folder.

Conclusion:

At Bamboo we are all continously striving to make products easier to use. We hope the new Web License Manager is one step in that direction. Remember no more installing LM 2.7 on each WFEs, no more worring about x86 or x64 machine and best of all no more searching for product assembly during activation.