IBM Support

Rational license migration from floating to tokens

White Papers


This white paper describes how to migrate IBM Rational licenses from floating to tokens.


Authors: Edwin Stalin, and Krishna Kumar

Table of Contents:

Introduction and Intent

Target Audience




License Key Center and Navigation

Passport Advantage

License Key Server Installers and Procedures

Types of Server Configurations

Jazz Token Server

The Transition

Pre-Deployment Planning Phase

Pre-Deployment Planning Phase: Client Environment Survey

Pre-Deployment Planning Phase: Token Environment Survey

Pre-Deployment Planning Phase: Token Checklist

Pre-Deployment Planning Phase: Capacity Planning

Deployment Phase

Post-Deployment Phase: Health Checks

Post-Deployment Phase: Token Usage Reports

Post-Deployment Phase: Parking of Licenses

Best Practices and More Information


Software production procedures have changed vastly over the past few years with various organizations going in for different models best suited for their environment. However, the key concept that has a raised is the necessity of having a smooth transition from one phase to another. Regardless of the model chosen, there are different tools and software in use. Managing and licensing these products is the key to cost effective software production. Token licensing offers this flexibility of cross product licensing that gives the ease of administration and better return on investment.

The token software license model is implemented and best understood as a variant of the existing floating license model. This model is effective for large, medium, and small enterprises who might take advantage of the entire Rational portfolio of products. With token licensing, you would not run into such a scenario.

When Rational token licenses are deployed, the IBM Rational License Key Center creates a generic license key "token" instead of a license key that is associated with individual product. The idea being that products do not check out a specific license, but rather a generic set of tokens for a product which can be reused by another user at a different point in time. What matters is the number of tokens that are required for a product to run and those numbers being made available in the "token pool''

The advantage of the token software license model is that it makes it easy for you to use the entire portfolio of Rational offerings rather than buying individual licenses for individual products. There are several advantages to this model of licensing, most importantly not running out of licenses for a specific product. A typical IT organization would follow a specific model of software production. Regardless of the model you chose, there are going to be different stages before having the final product for general availability. Consider a situation where you are currently in the "Modeling stage" of the software development lifecycle. Your key focus area with tools would require access to Modeling tools, and you might potentially face a situation of running out of licenses for Modeling tools, while having more than sufficient licenses for Requirements and other tools. This kind of scenario might be addressed with token licensing.


The primary goal of this paper is to familiarize the key stakeholders involved in a token transition project. The document provides a detailed step by step process involved in a transition. The steps described within this document is a collateral of knowledge gained from various token deployments undertaken by the IBM Rational Licensing Team.

Target Audience

The intended audience who might take advantage of this document are:

  • License Administrators
  • Site Technical Contacts
  • Management Contacts
  • License Key Center (LCK) Administrators
  • IBM Sales Staff
  • Internal technical engineers

...and virtually anyone who would like to understand the key concepts of token licensing and processes that are involved in an actual license migration.


The key advantages of token licensing are:

  • Tokens float across users, time, and tools. This allows people to use the right tool at the right time without having to cater for individual tool peak usage
  • Converts individual project tools into enterprise floating assets that can be used across geographies and organization.
  • Tokens add capacity but do not commit you to use specific tools forever.
  • Use capacity across multiple time zones and during low usage drive up utilization rate and hence provides better return on investment
  • Try out new tools without significant investment and with no risk of "shelfware"


License Servers: RLKS 8.1.1, 8.1.2, 8.1.3, 8.1.4, and later


As a part of the post sales effort, there are representatives from IBM Rational Licensing Support and the Rational Client Connect Team available to manage the token deployment must be introduced to your deployment team. You must commit at least one dedicated resource to the deployment of tokens depending on the volume of the deployment. The personnel must be familiar with the license key server software and FlexLM concepts. It is necessary for the Client Connect team and your deployment team to regularly meet to review potential issues that might arise.

Once the order is processed by the sales representative, it takes a few days before the order is processed and the respective license keys and installers are made available.

The License keys are available on the License Key Center website to manage keys. The product installers itself are available on the Passport Advantage website.

License Key Center and Navigation

Once you have licenses available in the License Key Center, you notice an entry as shown in "IBM Rational Tokens":

Select IBM Rational Tokens and proceed to license key generation:

Once a license key is generated, you have a block such as the one in this screen capture:

Passport Advantage

Depending upon the ELA or contract, the Passport Advantage website is updated with the product installers.

Note: Access to Passport Advantage is granted initially only to the Primary Contact and Site Technical Contact. However, either of them would have authority to grant access to more members. The access to Passport Advantage does not necessarily mean access to License Key Center as they are two different websites.

License Key Server Installers and Procedures

Token licensing works fundamentally on the same concepts as floating licenses. Hence, token licenses use the same license server infrastructure as the existing floating setup. Any current instances of Rational License Key Server (RLKS) 8.1.1 and above can be used.

To install the Rational License Key Server:

  1. Log in as a user with administrator rights on the local computer where the Rational License Key Server is installed.

  2. Extract the installation files for Rational License Key Server. The extracted files are the repository for Rational License Key Server. The installation files include IBM Installation Manager. You do not need to download Installation Manager separately.

  3. Navigate to the //RLKSSERVER_SETUP/disk1 directory.

  4. Double-click launchpad.exe. IBM Rational License Key Server splash screen opens.

  5. Read the release information by selecting Readme.

  6. Click Install or Update IBM Rational License Key Server to open the Installation Manager interface.

  7. Install IBM Installation Manager if it is not installed or the installed version is an earlier version than what comes Rational License Key Server.

  8. Installation Manager opens to the Install Packages window. Only Installation Manager is listed, Rational License Key Server is not listed.

  9. Install Installation Manager by following the instructions that are given in the Install wizard.

  10. Click Restart Installation Manager when the installation of Installation Manager finishes,

  11. Click Install to install Rational License Key Server.

  12. Select Rational License Key Server. Click Next.

  13. Click Next after the prerequisites are validated. To validate prerequisites again, click Recheck Status in the lower right corner.

  14. Accept the license agreement then click Next.

  15. Accept the default installation directory for the license server or enter a different installation directory. Default installation directory: C:\Program Files\IBM\RationalRLKS

    Note: For both the shared resources directory and Installation manager locations, either accept the default value or enter a different directory location.

  16. Click Next

    Note: You cannot change the location of the shared resource directory after Installation is Installed.

    Default Value of shared resource directory: C:\Program Files\IBM\IMShared

    Dafault Value of Installation manager directory: C:\Program Files\IBM\Installation Manager\eclipse

  17. Click Next after selecting more languages to install.

  18. Review the features to install. Click Next.

  19. Click Install.

  20. Click Finish.

Import the license keys and start the server. The license server will not start until license keys are installed. For more information, see the Start the Windows license server topic.

Types of Server Configurations

Token Licenses might be deployed in a wide range of setup topologies. Here is a brief description of each:

  1. Single License server: Single flex license server serving out tokens to all clients.
  2. Multiple License Server: License servers that are listed in a sequence for a specific client (load balancing)
  3. Redundant License Server: A fault tolerance setup to handle failure of the primary license server
  4. Disaster Recovery Setup: A duplicate license agreement to handle disaster scenarios.

Jazz Token Server

All Jazz enabled Rational products support token licensing. However, these are implemented in a 2-step procedure. Having the token license server setup is described above. The license server might serve licenses for FLEX & Jazz Products in tandem. An additional step of importing the relevant .jar file on the JTS server needs to be done. This is because it is the JTS server running the relevant CLM or Jazz enabled application that would be contacting the License server on behalf of the client. The token count for each product running the Jazz enabled application is submitted by the JTS and observed by the Flex license serving the tokens.

The .jar file for the tokens that must be applied on the JTS is available on the License Key Center. A screen capture for the same is provided below:

The Transition

The Token Transition Activity itself can be broken down to three different phases for the ease of implementation. Each phase is pivotal for the success of the next stage.

Your deployment team and the Client Connect team work in tandem to understand the necessities in the pre-deployment stage before moving on to actual deployment of tokens.

Pre-Deployment Planning Phase

The primary idea of this stage is for understanding your environment from a licensing environment perspective. There is a checklist provided by the Client Connect Team which tries to capture this information prior hand. The personnel that are involved from your side ensure that this data is made available for a smooth transition. The members that are involved in the migration must ensure that there is a documented migration plan with clear demarcation of roles and responsibilities for each of the parties involved.

Pre-Deployment Planning Phase: Client Environment Survey

  • The client environment survey tries to capture these environment specific details:
  • The Passport Advantage site numbers, on which the token licenses are registered.
  • If the Licenses are purchased on multiple site numbers, would there be a consolidation of these while implementing.
  • The number of license servers that have been identified for token deployment.
  • Approximate number of users who would be using the token server.
  • Physical location of the servers
  • Identify if there a requirement to be on specific versions of software in your environment. If yes, they need to be listed out in detail.

There is an impact on the actual transition for each of the activities described above, which might vary from a depreciated user experience for clients that are located across geographies to overload on the license servers.

Pre-Deployment Planning Phase: Token Environment Survey

The token environment survey is technical audit of the migration plan where you must verify the actual status of each of the servers, operating system versions, Rational product level, and network accessibility to ensure that they meet the minimum requirements for the migration to token licenses.

  • Server names
  • License server type
  • License server version
  • List of products which use the above listed license server
  • The operating system on the listed license server
  • Inter product dependency
  • Third party dependency

Pre-Deployment Planning Phase: Token Checklist

The token checklist is a quick summary of the migration plan and tries to capture a wide range of data:

  • List of site numbers
  • Planned time span for migration
  • Are there any products in use which are not supported by tokens

Each of the surveys are important and care must be taken to be as detail avoids any unexpected problems at a later stage

Pre-Deployment Planning Phase: Capacity Planning

The teams involved in the token transition should ascertain the number of licenses being served by the current floating license server. Based on the data from the checklist, conclude if there are any license server consolidations and then arrive at a calculation to understand the number of licenses which needs to be carved out for the new token license server.

The basis for arriving at the requirement number of tokens required is:

    Tokens required for 1 product = A X B


    A= Token value of the product

    B = No of intended users for the specific product


    Total tokens on the server is a sum of tokens required for each product.

A sample calculation is:

    Example: If the existing License server was serving 10 Rational DOORS floating license keys, then to implement the tokens the same server:

    Token value for Rational DOORS : 10

    No of intended users: 10

    Total no of tokens = 10 X 10

Hence you generate 100 Tokens to serve 10 Rational DOORS users. The token value is pre-decided by IBM and you can contact your IBM Sales representative for a product wide distribution of the latest token value.

Also, the value that is required by each product is mentioned in the respective INCREMENT block as shown in this screen capture for Rational DOORS:

Deployment Phase

The deployment stage is the actual transition that is based on the data gathering done in the Pre-Deployment Planning Phase and decisions that are taken. Further, there must be agreement on the transition model that needs to be implemented. These are some of the models of transition that might be adopted.

Isolated Staging Environment: You can prepare a new isolated staging environment that would have a sizeable number of tokens that might be used by client instances to pick the licenses. This would be dismantled once you ascertain the product and feature function using tokens. The idea here is to ensure Production readiness with all possible client instances.

Staging convertible to Production: This is a more feasible and recommended option as it avoids the unnecessary overhead of having test setups and also gives the advantage of scaling up the test environment to production once the involved teams are convinced of the behavior. The floating license server would ideally be running in parallel until the test system is deemed fit for full fledged production roll out. There must be an understanding with Licensing Support team and IBM Sales team to agree upon the dates and these must be strictly adhered to.

License Server Consolidation: Though this aspect is planned in the pre-deployment stage, the actual consolidation must be done in deployment phase. The purpose of consolidating some of the servers might be to have a centralized token server and hence reduce the overhead that is involved in terms of administration.

License Servers:behind DMZ/Firewalls: In certain instances it would not be feasible to consolidated all the licenses to a centralized license server as some of the client side instances would be behind a firewall or strictly inaccessible from outside networks. In such instances, there would be a need for a localized license server setup within the DMZ (De-Militarized Zone)

Client-Side License Pointing: If there is a change of license server, then the respective clients must point to the new token license server updated. For various Rational Products, this is done through:

    1. LKAD for Rational Products
    2. Environment Variable(TELELOGIC_LICENSE_FILE) for legacy Telelogic products
    3. Installation Manager for SDP products.

Post- Deployment Phase: Health Checks

Post deployment, the Client Connect team can be involved in a six week observation window where there would be a periodic health checks done to ensure that all issues related to the migration are ironed out.

Post- Deployment Phase: Token Usage Reports

The IBM Rational License Key Administration And Reporting Tool (ART), can be used to have periodic reports that are generated to understand and analyze the usage of the deployed Tokens. The ART provides a comprehensive summary including distribution and usage patterns for distributed token license deployments.

Here is a typical token distribution report:

Post- Deployment Phase: Parking of Licenses

Once the tests complete and a full fledged production roll out is complete, with all users picking token licenses, then it is mandatory to stop using all floating licenses. To avoid potential compliance issues with respect to the IBM Software License Agreement, you might want to register all floating licenses to a dummy server during the token contract that replaces the usage of any perpetual floating license keys.

Note: Activation kits cannot be returned once generated so post implementations of tokens every user should discard the use of activation kits from their respective machines to remain compliant with the IBM contract. For example:

Parking the licenses the following steps can be used:

  1. Return the licenses on LKC

  2. Regenerate the licenses again to a non-existing dummy name “PARKED_LICENSES” and dummy host ID.

Best Practices and More Information

Best practices are described in a wide range of articles, technotes and white papers:

This document provides a detailed step-by-step workflow of a token transition and for effective implementation of this in an enterprise setup. To contact the Rational Support or the Rational Client Connect team, see these documents:



[{"Product":{"code":"SSTMW6","label":"Rational License Key Server"},"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"Component":"General Information","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"","Edition":""}]

Document Information

Modified date:
17 June 2018