IBM Support

Token licensing for Maximo 7.6.1.2 systems

General Page

You can enable, configure, and use token licensing in Maximo® 7.6.1.2 systems.

For token licensing information for Maximo 7.6.1 and 7.6.1.1 systems, see the Token licensing for IBM® Maximo® Asset Management article on IBM Support (https://www.ibm.com/support/pages/token-licensing-maximo-asset-management).

Overview

Token licensing is a fixed-term license control method. You can use token licenses, which are also known as tokens, to license Maximo Asset Management, various Maximo industry solutions, and Maximo add-ons. The total number of tokens that you purchase is based on your predicted usage of the tokens. Tokens have a 1-1 relationship to license keys that you store and manage in IBM Rational® License Key Server. A request is sent from the Maximo server to Rational License Key Server whenever a token is consumed or released. The UserAnalyzer cron task in the Maximo system tracks and updates token usage data so that you can determine how tokens are being used.

Before you enable token licensing, consider the following information:

  • Perpetual or non-token licenses and token licenses cannot be mixed on the same server.
  • The License Usage Monitor application does not report on token licenses and cannot be used with token licensing.

You enable token licensing after you set up your Maximo system. To enable token licensing, you complete the following steps:

  1. Configure Rational License Key Server and Rational License Key Administrator.
  2. Configure the client file.
  3. Configure the Token Licensing Setup application.
  4. If you have IBM Maximo for Aviation, associate any custom security groups with similar, default security groups.

If you used token licensing for 7.6.1 and then upgraded directly to 7.6.1.2, you do not need to re-enable token licensing, but you must refresh the license keys for your system after you upgrade. For more information, see Refreshing the token license keys.

Token usage behavior

The installed Maximo products determine when tokens are consumed and released. The user's access type and whether multiple Maximo environments or sessions are used determines how many tokens are consumed. The following token usage rules apply only to 7.6.1.2.

Consumption and release of tokens

In most cases, tokens are consumed when a user logs in and released when a user logs out. When a user accesses an application that is part of an add-on product, the tokens that are consumed when the user logs in cover the add-on usage.

The following products uniquely consume and release tokens:

  • For IBM Maximo Anywhere, tokens are consumed when the user accesses an application.
  • For IBM Maximo APM - Asset Health Insights On-Premises, tokens are consumed when the Maximo server is running and released when the server is no longer running. Tokens are not consumed when users log in.
  • For IBM Maximo Enterprise Adapter for Oracle Applications and IBM Maximo Enterprise Adapter for SAP Applications, tokens are consumed when the Maximo server is running and released when the server is no longer running. Tokens are not consumed when users log in.

No tokens are consumed for Maximo integration framework users for any Maximo product if the user logs in to a Maximo system as part of an automated process.

For all products, closing the browser does not release the tokens. If a user does not manually log out of the Maximo system before the browser or browser tab is closed, tokens are not released until the timeout value. The timeout value is specified in the web.xml file and is 30 minutes by default. If the timeout is longer than 30 minutes, token usage might be higher than expected. By default, every 5 minutes, the mxe.tokenlic.cleanupinterval property is used to scan the Maximo system for these inactive sessions. If a session is located, it is ended, and the tokens are released.

Access types

Access types determine how many tokens a user consumes. Access types are automatically assigned according to a user's security profile. Configure your users' security profiles to ensure that each user is assigned the access type that you want the user to have. If a product is installed in your system but no user has access to that product, that product does not impact the number of tokens that are consumed for any user.

Access types are assigned to users when the UserAnalyzer cron task runs. By default, the UserAnalyzer cron task runs daily. In the Token Licensing Setup application, you can edit the schedule for the cron task by selecting More Actions > Data Collection Settings. For access types to be accurately assigned, all installed Maximo products must be specified in the Token Licensing Setup application. You complete this step when you enable token licensing.

Access types are associated with licenses, and each access type inherits the qualities of the lower access types. For example, for a user to be assigned a limited access type, the user must qualify for limited and express access types. All users qualify for the self-service access type. All users can access the Maximo self-service applications, such as the Self-Service Requestor and the Desktop Requisitions applications, and that access does not affect the assigned access type.

The following access types are available:

Access types
Access type Assigned to Tokens consumed
Self-service

Users who can access only the self-service applications.

None.
Express

Users who have read-only access to one or more applications, can change the status of records, and can update work orders that are assigned to them.

Fewer tokens than any other access type except for the self-service access type.

Limited

Users who can update data in three or fewer modules and have read-only access to one or more applications. For a user to be assigned a limited access type, the user must not be able to access the Administration module. Users can update work orders that are assigned to them, and the Work Orders module is not included in the three-module limit.

More tokens than the express access type but fewer tokens than the full access type.

Full

Users who have read-only and update access to four or more modules.

The most tokens.


Multiple environments and sessions 

If a single username is logged in to several Maximo sessions simultaneously, and each session involves identical Maximo products, tokens are consumed for only one session. If the sessions do not involve identical Maximo products, tokens are consumed for each session. If a user logs in to multiple, simultaneous sessions in multiple complete Maximo environments, such as a development environment, a test environment, and a production environment, the tokens are still allocated by username and product combination. A complete Maximo environment is a complete Maximo instance on its own database.

The following examples describe token usage when multiple complete Maximo environments and sessions are used:

  • Example 1: A system administrator logs in to Maximo Asset Management in the development environment. After the system administrator logs in, the system administrator opens another browser and logs in to Maximo Asset Management in the production environment. Because the user ID and product combination is the same and the system administrator logs in to the development environment first, tokens are consumed only when the system administrator logs in to the development environment. Tokens are not consumed when the system administrator logs in to the production environment.
  • Example 2: A system administrator logs in to Maximo Asset Management in the development environment. After the system administrator logs in, the system administrator opens another browser and logs in to an instance of Maximo Asset Management that includes an add-on in the production environment. The user ID is the same for each environment, but the products are different. Because the products are different, tokens are consumed when the system administrator logs in to the development environment, and more tokens are consumed when the system administrator logs in to the production environment.

If you have Maximo Enterprise Adapter installed on your system and you have multiple environments, when the Maximo server starts running, all environments consume individual sets of tokens and retain those tokens until the Maximo server stops running.

For example, you have a development environment, a test environment, and a production environment. When the Maximo starts running, each of those environments consumes Y tokens and retains those tokens until the Maximo server stops running. 

Conditional token usage rules

If a user does not have an assigned access type or if products are not specified in the Token Licensing Setup application, other rules are used to determine when tokens are consumed and released and how many tokens are used. A user might not have an assigned access type if the user is a new user and the cron task has not had the opportunity to run. The rules for multiple sessions and environments still apply in these scenarios.

The following table describes these rules for a single user session in a single complete Maximo environment:

Token usage behavior if an access type or product is unavailable
Scenario Rules
User logs in to Maximo Asset Management.

The predefined number of tokens for Maximo Asset Management are consumed when the user logs in and are released when the user logs out.

User logs in to an instance of Maximo Asset Management that includes one industry solution.

The predefined number of tokens for that industry solution are consumed when the user logs in and released when the user logs out.

User logs in to an instance of Maximo Asset Management that includes multiple industry solutions.

When a user logs in, the highest predefined number of tokens for one of the industry solutions is consumed, and the predefined number of tokens for an add-on are also consumed for each of the other industry solutions. Tokens are released when the user logs out.

For example, IBM Maximo for Oil and Gas, which requires Y tokens, and Maximo for Aviation, which requires Z tokens, are both installed on the same system, but Maximo for Aviation is not specified in the Token Licensing Setup application. Z is a higher number than Y. X is the predefined number of tokens for add-ons. When a user logs in, Z plus X tokens are consumed.

After a user logs in to Maximo Asset Management, the user accesses an application that is part of an add-on. The add-on is not a part of an installed industry solution.

The predefined number of tokens for Maximo Asset Management are consumed when the user logs in and more tokens are consumed when the user accesses the application. The application tokens are released when the user exits the application, and the Maximo Asset Management tokens are released when the user logs out.

These rules do not apply to IBM Maximo Calibration or to IBM Maximo Linear Asset Manager.

After a user logs in to Maximo Asset Management, the user accesses an application that is part of Maximo Calibration, Maximo Linear Asset Manager, or both add-ons.

In addition to the Maximo Asset Management tokens that are consumed at login, when the user accesses the application, the predefined number of tokens for the add-on or, if an application is affected by both add-ons, the combined predefined number of tokens for both add-ons is consumed. The tokens are released when the user exits the application.

For example, Maximo Calibration and Maximo Linear Asset Manager both affect the Work Order Tracking application. If both products are installed on the same system and if Maximo Calibration requires Y tokens and Maximo Linear Asset Manager requires Z tokens, Y plus Z tokens are consumed when the user accesses the Work Order Tracking application.

Maximo Linear Asset Manager and Maximo Calibration both affect the following applications:

  • The Work Order Tracking application
  • The Assets application
  • The Preventive Maintenance application
User accesses an IBM Maximo Anywhere application.

The predefined number of tokens for Maximo Anywhere are consumed when the user accesses the application and released when the user exits the application.

User accesses Maximo APM - Asset Health Insights On-Premises.

No tokens are consumed. Tokens are consumed when the Maximo server is running and released when the server is no longer running. The number of tokens that are consumed for the server is determined by the resource value units (RVU).

User accesses Maximo Enterprise Adapter for Oracle Applications or Maximo Enterprise Adapter for SAP Applications.

No tokens are consumed. Tokens are consumed when the Maximo server is running and released when the server is no longer running.

A Maximo integration framework user logs in to a Maximo system as part of an automated process.

No tokens are consumed or released.


Token usage data

After the UserAnalyzer cron task runs, you can review token usage data for your users in the tokenlicusers database table, or you can enable the Token profile tab in the Users application.
To enable the tab, complete the following steps:
  1. In the Security Groups application, select a security group.
  2. On the Applications tab, in the Applications table, select the Users application.
  3. In the signature option rows, open the row for the User Token Profile signature option.
  4. Select the Grant Access checkbox and save the security group.

Server configuration options

You can configure your license server or servers in multiple ways, such as by configuring stand-alone servers or servers in one or more triads. The configuration of your license server or servers affects the overall token licensing performance. Each licensing server is an instance of Rational License Key Server.

Stand-alone servers

Each stand-alone license server requires its own license file, and you must divide the tokens among the license servers. If you have multiple stand-alone license servers and one of the license servers cannot complete a token request, another license server is used to complete the request. When you enable token licensing, you configure the order that license servers are used when you specify license server addresses in the Server Address field of the Token Licensing Setup application.

Triads

A triad, which is also known as a system of redundant servers, is an instance of three, connected license servers. You cannot set up both triads and stand-alone servers. One license server in the triad provides the tokens on behalf of the other license servers in the triad. If one of the license servers is down, your users are not affected because the other two license servers can still run. If two license servers are down, the remaining license server does not run.

You do not need a special port or URL to set up a triad. However, all license servers that are a part of a triad must be geographically aligned with the associated Maximo server. Significant time zone differences between a triad and the Maximo server can result in increased latency or failure to complete a request.

For more information about triads, review Configuring a license server on Microsoft™ Windows™ (https://www.ibm.com/support/knowledgecenter/SSSTWP_8.1.4/com.ibm.rational.license.doc/topics/r_redundant_servers_win.html) or UNIX (www.ibm.com/support/knowledgecenter/SSSTWP_8.1.4/com.ibm.rational.license.doc/topics/r_lic_server_unix.html).

Performance

The performance of a license server is directly proportional to the bandwidth and latency of the network that the license server is connected to. The consumption of network bandwidth is directly proportional to the number of users who are requesting tokens from the license server and the availability of tokens.

Performance is measurable in ping time. Ping time is the time that is required for a request to be sent from the Maximo server to the license server plus the time that is required for that request to be acknowledged by the license server. Any value that is less than the request timeout for the installed Maximo products is an acceptable ping time for the license server.

To improve performance, you might complete the following tasks when you set up your license servers:

  • Connect your license server to a network that has a latency of at least 100 milliseconds (ms).
  • Add a license server to the same geographical region as the users of that server.
  • Use Linux® or UNIX for the license server. By using Linux or UNIX, you can have more control over the file descriptor size, which you can use to control performance. If the license server is running on Windows and more than 3000 users are requesting tokens, distribute the tokens across multiple license servers so that each license server is handing requests for no more than 3000 users.

Enabling token licensing

To enable token licensing, complete the following steps. Review the end of this document for troubleshooting information.

  1. Configure Rational License Key Server and Rational License Key Administrator.
  2. Configure the client file.
  3. Configure the Token Licensing Setup application.
  4. If you have Maximo for Aviation, associate your custom security groups with similar, default security groups.
  5. Verify your token enablement.

Prerequisites

Ensure that you have the following products, permissions, and resources before you enable token licensing:

  • A Maximo 7.6.1.2 system.
  • An IBMid.
  • A Rational License Key Center (https://www.ibm.com/support/pages/ibm-support-licensing-start-page) account. You use this account to manage Rational License Key Server. If you are the primary site contact or site technical contact for your Passport Advantage account, you are a member of the Rational License Key Center account and can use the instructions in the welcome email to access the account. As part of the account setup, you must create a password within 72 hours of receiving the welcome email. If you cannot locate your welcome email or are unable to access your account, in Rational License Key Center, select Forgot your password. Instructions for resetting your password are sent to your email.

    If you are not the primary site or site technical contact, complete one of the following tasks:

  • Request access from your primary site contact.

  • If you have the site number for the license purchase, on the Rational License Key Center login page, select Don’t have a password, and complete the Join Account form. If you have the sales order number, specify the number. An email is sent to the administrator of the Rational License Key Center account to request approval for your membership.

For more information about setting up a Rational License Key Center account, see How to access Rational License Key Center (https://www.youtube.com/watch?v=aLte61Ll4yc&feature=youtu.be).

Configuring Rational License Key Server

To configure Rational License Key Server, install the product and then generate and import the license key for each license server.

  1. Install Rational License Key Server and Rational License Key Administrator.
    1. Download the files from Fix Central. For instructions, see the online product documentation  (www.ibm.com/support/knowledgecenter/en/SSSTWP_8.1.6/com.ibm.rational.license.doc/topics/t_download_files_support.html).
    2. Complete the installation. For installation instructions, see the online installation product documentation (https://www.ibm.com/support/knowledgecenter/en/SSSTWP_8.1.6/com.ibm.rational.license.doc/topics/c_node_installing.html).
  2. For each license server, generate a license key. 
    1. Log in to Rational License Key Center (https://www.ibm.com/support/pages/ibm-support-licensing-start-page).
    2. On the Get keys screen, click IBM Tokens.
    3. In the box for your product or unique sales order, in the LICENSE KEYS FOR THIS ORDER section, click the checkbox. 
    4. Click Next.
    5. In the Number of keys to generate field, specify the number of tokens that you want to assign to the license server. 
    6. In the Existing hosts and Server Configuration fields, select the options for your license server.
    7. In the Host ID Type field, select an option for the hardware that you are registering your key for.
    8. In the Host ID and Hostname fields, specify the values that are included in Rational License Key Administrator. To view this information, in Rational License Key Administrator, select License Keys > Host Data.
    9. Click Generate. 
  3. For each license server, import and verify the license key.
    1. On the View Licenses By Host screen, click Download License Keys. To download and import the license key, complete the steps that are provided in the License Key Installation Instructions section.
    2. After the license key is imported, in Rational License Key Administrator, review the license key information and ensure that accurate Maximo products, license types, and license quantities are displayed.
Repeat these steps for each license server and each license server's unique license key.

To learn more about how to configure, administer, and use license servers, see the Rational License Key Server online product documentation (https://www.ibm.com/support/knowledgecenter/en/SSSTWP_8.1.6/com.ibm.rational.license.doc/helpindex_RCL.html).

Configuring the client file

You configure the client file for each Maximo server so that the Maximo server can communicate with its associated license server or servers.

  1. Download the client files.zip file, which is attached to this article.
    client files.zip
  2. Extract the files from the client files.zip file. The client files.zip file contains two files. If you are using Windows, your client file is the rcl_ibmratl.dll file. If you are using Linux or UNIX, your client file is the librcl_ibmratl.so file.
  3. Relocate your client file to any directory that your Maximo server can access.
  4. Add the following text to the jvm parameter of the Maximo server. Replace the client file directory variable with your client file directory: 
    -Djava.library.path=client file directory
  5. Repeat these steps for all Maximo servers.
  6. Restart the application servers.

Configuring the Token Licensing Setup application

You use the Token Licensing Setup application to connect your Maximo system to Rational License Key Server and manage the installed products.

  1. Enable the Token Licensing Setup application.
    1. Log in to your Maximo system as the system administrator.
    2. In the Security Groups application, open the MAXADMIN security group.
    3. On the Applications tab, filter for token licensing setup and then select the Grant Access checkbox for the application.
    4. Save the security group.
    5. Log out and log back in to the Maximo system.
  2. In the Token Licensing Setup application, in the Server Address field, specify the addresses for your license servers.
    • The format for a single address is port@hostname.
    • If you are using Linux or UNIX, separate multiple addresses by using colons (:).
    • If you are using Windows, separate multiple addresses by using semicolons (;).
    • Separate multiple addresses for redundant license servers or a triad by using a comma (,).
    • If you specify a hostname that is not fully qualified, the connection to the server might not be established. If the connection is not established, specify a fully qualified hostname. 
    • If you are using stand-alone license servers, the order of the servers in the field determines the order that license servers are used to complete at token request if one of the license servers cannot complete a request. For example, if you specify A;B;C and server A cannot complete a request, server B is used to complete the request.

  3. Click Test. If the connection is successful, a confirmation message is displayed.
  4. If the connection is successful, click Save. The server addresses are added to the mxe.token.licensepath system property. Do not click Save unless the connection is successful.
  5. Add the Maximo products that are installed in the current environment to the Manage Products dialog box.
    1. In the More actions menu, click Manage Products.
    2. In the Manage Products dialog box, click New Row.
    3. In the Product Name field, select an installed product.
    4. In the License Type field, select the license type.
    5. Click OK and save the row.
    6. Change the status of the row to active.
    7. Repeat these steps for all other installed products.
       
Associating Maximo for Aviation security groups

If you have Maximo for Aviation, you must associate custom security groups with default security groups. The default security groups are the security groups that are provided with your purchase of Maximo for Aviation. Custom security groups include cloned security groups. When security groups are associated, the custom security group impacts token usage and access type assignment identically to the default group. The custom group must provide equal or fewer security privileges than the similar group, and a custom group can be associated with only one similar group.

  1. In the Token Licensing Setup application, in the More actions menu, click Associate security groups.
  2. Click New Row.
  3. In the Custom Group field, select a custom security group.
  4. In the Similar Group field, select a similar, default security group.
  5. Save the row.
Verifying your token enablement

To verify that token licensing is enabled, generate token information from each of your license servers.

Before you begin, ensure that the following events occurred in the following order:

  1. The UserAnalyzer cron task ran. Access types are not assigned to users until the cron task runs. If a user who does not have an assigned access type logs in, the token usage by that user might be higher.
  2. Actions that cause tokens to be consumed have occurred. For example, ensure that the Maximo server is running and that users of varying security permissions logged in to the Maximo system.
  3. The UserAnalyzer cron task ran again. The first time that the cron task ran, access types were assigned, but because no users had logged in prior to the cron task running, token usage was not reported.

Then, complete the following steps:

  1. In a command line, open the Rational License Key Server directory.
  2. Run the following command. Replace the port and hostname variables with the port and hostname of the license server.

lmutil lmstat -a -c port@hostname

If token licensing is enabled, the output contains license server details, feature names, and the times and number of tokens that were consumed.


Refreshing the license keys 

If you used token licensing for 7.6.1 and upgraded directly to 7.6.1.2, you must refresh the license keys. You do not need to re-enable token licensing for 7.6.1.2.

  1. Log in to Rational License Key Center and click View keys by host.
  2. For each of your license servers, complete the following steps:
    1. Click Refresh.
    2. Download the new license key.
    3. In Rational License Key Administrator, click License Keys > Import License Key(s).
    4. Import the new license key into the license sever.

In Rational License Key Administrator, review the license key information and ensure that accurate Maximo products, license types, and license quantities are displayed.

Troubleshooting token licensing
You can troubleshoot some issues that can occur when you enable or use token licensing. Before you troubleshoot token licensing, set the tokenlic logger to DEBUG and set the UserAnalyzer cron task schedule to a shorter frequency. To set the schedule to a shorter frequency, in the Token Licensing Setup application, in the Data Collection Settings dialog box, update the Schedule field. By setting a shorter frequency, you can more quickly determine whether the issue is resolved.

Connection is not established with the license server

In the Token Licensing Setup application, if the connection to the license server is not successful, ensure that the license server is running. Then, from the Maximo application server host machine, use telnet to connect to the lmgrd port of the license server.

An unsuccessful connection to the license server is saved

In the Token Licensing Setup application, if an unsuccessful connection to the license server is saved, you can undo the configuration by running the following database query:

select * from propvalue where propname='mxe.tokenlic.licensepath';

Then, by running the following database query:

update maxpropvalue set propvalue=null where

propname='mxe.tokenlic.licensepath';

License server cannot complete a token request

A license server can be unable to complete a request for the following reasons:

  • The network or firewall that is used for the license server is unavailable or the quality of the network is poor. If a poor network is used, the requests might time out before the requests reach the license server. For more information about improving performance, see Server configuration options.
  • The user who requests the tokens is blocked from the license server. You can block or unblock users from a license server by using the license option file.
  • The license server has no available tokens. Consider purchasing more tokens or review your users' security profiles to ensure that security profiles are not increasing a user's access type unnecessarily.
  • Many users are simultaneously requesting tokens from a license server. If many users are requesting tokens, the Maximo system can be unresponsive and long delays can occur between the time that the tokens are requested and when the tokens are provided. Consider purchasing more tokens or improving the system or server performance. For more information, see Server configuration options.
  • A significant time zone difference exists between the license server and the Maximo server. In this case, the following error occurs in the license server log file after a license request is sent: Licensing Error: Clock Difference too large between client and server. Geographically align your license server with the associated Maximo server.

Token Profile tab shows excessive token usage

If an erroneously high number of token licenses is tracked on the Token Profile tab in the Users application, complete the following steps:

  1. In the Application Designer application, open the Users application. 
  2. Click the Token Profile tab and then right-click the Token Licenses table.
  3. In the Table Properties dialog box, clear the Business Object field.
  4. Save your changes.

The BMXAA4214E error occurs for UserAnalyzer cron task

If the BMXAA4214E error occurs for the UserAnalyzer cron task, ensure the latest interim fix for the Maximo system is installed and then complete the following steps:

  1. In the maximo_root/deployment directory, open the buildmaximoear.xml file. 
  2. Append the following text to the end of the maximo.businessobjectsclasspath property: lib/license_metric_logger_2.1.1.201507131115.jar
  3. Rebuild and redeploy the EAR file..

    The following text is an example of this change:
    <property name="maximo.businessobjectsclasspath"> lib/license_metric_logger_2.1.1.201507131115.jar

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSLKT6","label":"IBM Maximo Asset Management"},"ARM Category":[{"code":"a8m50000000CbLKAA0","label":"General->Misc - Documentation"},{"code":"a8m0z0000001hDuAAI","label":"System->Token Licensing"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"7.6.1","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

Document Information

Modified date:
02 August 2021

UID

ibm16234000