License Key Server Administration and Reporting Tool FAQs

Attention: The license server log files (lmgrd.log, lmgrd.log.back, and ibmratl_timestamp.log) and option files (such as ibmratl.opt) are the source of data for the reporting tool. Do not delete or modify these files. Doing so will result in license usage reporting inaccuracies. For more information, see technical document http://www.ibm.com/support/docview.wss?uid=swg21671165.

What can I do to upgrade License Key Server Administration and Reporting Tool from V8.1.5 to V8.1.5.1?

When you upgrade from License Key Server Administration and Reporting Tool V8.1.5 to V8.1.5.1, you must run the setupARTDB2 scripts with the latest RCL_Database_DB2.sql file provided with License Key Server Administration and Reporting Tool V8.1.5.1.

Important: When you run the latest script, there is no impact in the existing data.

How do I know whether the ART application is started?

To ensure that the License Key Server Administration and Reporting Tool is started, check for the log line containing the string similar to Application rcladmin started in X.Y seconds. at the following locations:

For Windows: RLKSAdmin_install_location\work\rcladmin\logs\console.log
UNIX: RLKSAdmin_install_location/work/rcladmin/logs/console.log

Does License Key Server Administration and Reporting Tool support automatic restart of the agent and the ART when the system is restarted?

The software supports automatic restart of ART and the agent on all platforms. See Starting License Key Server Administration and Reporting Tool on system startup.

How does License Key Server Administration and Reporting Tool respond to database unavailability when it is started for the first time?

On the Database Configuration page, the test connection can continue to fail during the database setup process, until the database is reachable again.

How does License Key Server Administration and Reporting Tool respond to database unavailability for an administrator user after completing the database setup?

For an administrator user, the License Key Server Administration and Reporting Tool responds to database unavailability in the following conditions:

If the database is available, normal flow occurs.
If the database is not available, you are redirected to the Database Administration page. The page displays last saved configuration details with the following message:
```
A connection could not be established based on the given parameters. Either the server does not exist or it's unreachable.
```
To test your connection you can click the Test Connection button. If you have not modified any parameter, you are redirected to the Server Administration page.
If you choose to modify the last saved parameters before the test connection succeeds, the product enables the Save option and displays the following message:
```
Test connection succeeded. Save the changes and then restart the application server for them to take effect. 
```
When the connection succeeds, you can either go to the Server Administration page or save the details and restart the License Key Server Administration and Reporting Tool. You cannot access any License Key Server Administration and Reporting Tool functions except login and logout.

How does License Key Server Administration and Reporting Tool respond to database unavailability for a non-administrator user after completing the database setup?

For a non-administrator user, the License Key Server Administration and Reporting Tool responds to database unavailability in the following conditions:

If database is available, normal flow occurs.
If the database is not available, the system displays a status page with the following message:
```
Database is unreachable. Contact your administrator.
```

How do I change the synchronization time with the LDAP server after I create chargeback groups in ART?

By default, ART automatically retrieves the updated information for the chargeback groups from the LDAP server at midnight, local time. To change the setting, open the RCLServerAdminConfiguration.properties file:

Windows: C:\Program Files\IBM\ICL\RLKSAdmin\server\conf\rcladmin
UNIX: install_location/server/conf/rcladmin

Locate the ldap.group.synchronize.interval property. Set the value to any positive integer, and then restart the server to apply the changes.

For example, if you set the value to 43200, the synchronization process occurs 43200 seconds (12 hours) after you restart the server. Then, the synchronization occurs every 43200 seconds.

Why must I specify the secure LDAP certificate again after I upgrade to version 8.1.5?

In your ART old installation, the location of the SSL certificate of the secured LDAP server is imported into the keystore file at old_install_location/server/jre/lib/security/cacerts. Because you must uninstall your prior version of ART, the data migration does not include the SSL certificate information. ART cannot communicate with the secure LDAP server without this certificate. You must provide the SSL certificate information when you install ART version 8.1.5.

How do I configure ART with LDAP using the SSL connection?

To configure the reporting tool with LDAP using the SSL connection, perform the following steps:

Place the CA-signed SSL certificate at a location, for example, C:\LDAP_SSL and name this certificate as ART_LDAP.cer.
Navigate to <ART_installation_directory>\jre\bin from the command line/shell.

Run the following command:

keytool -import -alias <Choose an alias> -file "C:\LDAP_SSL\ART_LDAP.cer" -keystore "<ART_installation_directory>\servers\rcladmin\resources\security\ART.pfx" -storepass rcladmin -storetype pkcs12 -noprompt

Check the following message on the prompt for successful import:
```
Certificate was added to keystore
```
Restart the License Key Server Administration and Reporting Tool.

Why doesn't ART start after I change the LDAP administrator password?

See the How to handle LDAP admin user password change in ART technical document for steps to perform when the LDAP administrator password is modified after configuration with the reporting tool.

Perform the following steps to change the LDAP administrator password:

Shut down the License Key Server Administration and Reporting Tool.
Remove the .LDAPInUse file from location RLKSART_Installation_Location\servers\rcladmin\conf\rcladmin\.
Important: This file is hidden on Windows operating system.
Open the RLKSART_Installation_Location\servers\rcladmin\conf\rcladmin\RCLServerAdminConfiguration.properties file and comment the line containing the LDAP.URL configuration.
Restart the License Key Server Administration and Reporting Tool and login with the default user name rcladmin.
Reconfigure the LDAP settings.
Important: The user must key in all the configuration details, with the new password.
Save the configurations and restart the License Key Server Administration and Reporting Tool.

Why is the `lmgrd.log.backup` file created after I start reporting?

Do not delete the .backup file. The agent module creates a backup of the lmgrd.log file and works on the backup to resolve issues that are related to file-overwrite if a license server is restarted.

Why is a log file such as `ibmratl_time_stamp.log` created after I start reporting?

The agent module switches the debug log file to ibmratl_time_stamp.log to resolve issues that are related to the license server debug log file overwrite if a license server is restarted.

After I start reporting, why do I see multiple files like `ibmratl_time_stamp.log` over time?

The agent module switches the debug log file to ibmratl_time_stamp.log when the size of the current log file exceeds 500 MB.

To configure this value, modify the LOGFILE_MAX_SIZE property in the rclagentconf.properties file. You must restart the agent for the new value to take effect.

How do I interpret reports for multiple groups that contain report definitions with the same name as a parameter?

If you have a report definition that includes multiple groups with the same name, then the report differentiates the archived and active groups with the same names.

Example:

Chargeback report showing active and archived groups

How do I create an options file after I start the reporting function?

The agent module creates an options file that contains the DEBUGLOG attribute. The ibmratl.opt options file is created in the directory that contains the license files. To add more options to control the license server, update this options file.

Why do the bars or lines in my charts not appear in the colors that I specified on the Preferences tab?

You must first define the values of the parameters on the Parameters tab, and then move to the Preferences tab to specify the colors, type, and dimensions to draw the chart in. While the Preferences tab is open, click Run to generate the report. If you leave the Preferences tab, all the values that you set are lost.

Does the remove reporting operation delete the report definitions that pertain to that license server?

The remove reporting operation does not delete the saved report definitions. The operation removes the data source from the backend LQE database. Therefore, some or all of the parameters of the report definition do not display correctly. In ART, remove the report definitions after the remove reporting or after the remove server operation.

How do I generate reports for product names that contain Japanese characters?

If your license server log file contains product names that are logged in Japanese and you try to run token reports for IBM® Engineering Lifecycle Management (ELM) products, the reporting tool cannot process the product names. To resolve this issue, complete the steps in technical document http://www.ibm.com/support/docview.wss?uid=swg21667198.

Why does License Key Server Administration and Reporting Tool not showing chart-based reports (like Peak usage) in the View Saved Reports when upgraded from V8.1.4 or V8.1.5 to V8.1.5.1 ?

If you cannot view the chart-based reports, access the License Key Server Administration and Reporting Tool URL using fully qualified domain name instead of IP Address or run the report definition for the same duration and export it.

Attention: The token distribution report is not available starting from License Key Server Administration and Reporting Tool V8.1.5.3.

Why removing reporting in the License Key Server Administration and Reporting Tool fails when you manually removes data from the database? What can I do to resolve this error?

When you manually remove reporting data from the database and restart the agent and the Administration and Reporting Tool, you might get this error message:

CRALUA0018F: The remove Reporting operation failed with exception.

To resolve this error message:

Stop the License Key Server Administration Agent.
Go to this folder location: C:\Program Files\IBM\ICL\RLKSAdminAgent\servers\rclagent\apps\rclagent_resources.
Delete the backup and the Derby folder.
Refresh the server from the License Key Server Administration and Reporting Tool. Refreshing the server changes the reporting status to “Not running”.
Remove the server from the License Key Server Administration and Reporting Tool. You get the following message: License server removed successfully.

Why reporting operation on License Key Server Administration and Reporting Tool does not run properly and no data is available for report generation?

When you upgrade the License Key Server Administration Agent and License Key Server Administration and Reporting Tool from version 8.1.4.9 or earlier to 8.1.5 or later but do not perform the data migration using Data Migration step in the setup wizard, it does not migrate existing License Key Server Administration Agent metadata to latest database. As a result, the License Key Server Administration and Reporting Tool and License Key Server Administration Agent are no longer in sync and therefore the reporting operation on agent does not run properly and no data is available for report generation.

Following are the most common symptoms when you face such problem:

The operation Start Reporting succeeds.
The reporting status is Running but the Last read change log time field in Reporting tab on server administration page shows Not Available status.
You get the following error message when you try to perform Remove Reporting on related License Key Server Administration Agent:

CRALUA0018F: The remove Reporting operation failed with exception
The license server corresponding to related agent is not listed in create report definition page.

You must add related agent to License Key Server Administration and Reporting Tool to resolve this issue:

Connect to artdata database and execute the following query:
INSERT INTO RCLADMIN.REPORTING_AGENTS (HOSTNAME_PORTNUMBER, TIME_OF_LAST_DATA_FETCH, START_FACT_INDEX, END_FACT_INDEX, REPORTING_STATUS) VALUES (‘_, '2018-11-01 00:00:00.000000', 0, 0, 0);
Restart the License Key Server Administration and Reporting Tool.
Perform Remove Reporting on related agent. Wait till operation completes successfully.
Stop License Key Server Administration and Reporting Tool.
Stop License Key Server Administration Agent.
Remove the backup folder from location:.<<Agent Installation Location>>\servers\rclagent\apps\rclagent_resources
Clear the agent logs.
Start the License Key Server Administration Agent.
Start the License Key Server Administration and Reporting Tool.
Perform Start Reporting on related agent. Wait till operation completed successfully.
Wait for few minutes and look at the Last read change log time field. It should show a timestamp.
Wait for 10 minutes and navigate to the create report definition page. You can see license server corresponding to the agent listed there.
Note: If there is a redundant server setup, repeat the above steps for each of the three servers in triad.

How do I determine when to use custom chargeback groups?

If ART is configured to use LDAP for authentication, then ART can use LDAP-based chargeback groups for reporting. Custom-based chargeback groups are flexible and are not tied to any LDAP group or LDAP structure. You can use custom chargeback groups in addition to your LDAP-based chargeback groups to track the usage of IBM Rational® products that do not use LDAP.

For more information, see Creating, modifying, and archiving custom chargeback groups.

How do I enter non-English-language user names in a custom chargeback group file?

If you are entering non-English-language user names into your custom chargeback group file, you must use a text editor that saves the file with UTF-8 encoding. UTF-8 encoding supports all non-ASCII characters, so you can type the user names that contain non-ASCII characters as-is. Ensure that you save the file with UTF-8 encoding. For detailed steps, see Creating custom chargeback group files.

How are the costs computed and presented in a group-based chargeback report for a user who is part of more than one chargeback group?

For example, you have a user who is part of more than one chargeback group, such as G1 and G2. You create a report definition for a group-based chargeback metric where both of the groups, G1 and G2, are included. When you run this report definition, the cost for the common user is computed as cost C1. The cost C1 is included in the cumulative costs for both of the groups. Therefore, there is an overlap of costs among the groups, so the sum of the cost values of both groups is not accurate. To obtain the actual sum of cost values for both groups, identify the common user and exclude the cost of C1 from G2.

Why can't I create group-based chargeback reports to obtain historical data?

You can create group-based chargeback reports only from the time the groups are created in ART. See the LDAP group-based chargeback reports cannot be created for historical data technical document.

Can I delete a chargeback group in ART?

No. When you create a chargeback group, the group cannot be deleted. It must be archived. See Creating, modifying, and archiving LDAP chargeback groups.

What happens when I archive a chargeback group in ART?

When you archive a chargeback group in ART:

The group data is not synchronized with the LDAP server.
You can view the details of the archived group. However, you cannot modify or edit the archived group.
You can use the archived group to create group-based chargeback reports.
You can create another group with the same name as the archived group.

Can I create group-based chargeback reports that contain both active and archived groups?

Yes, you can create group-based chargeback reports for both active and archived groups as parameters.

How do I perform the license server administration options on Windows platforms that support UAC?

On platforms that have UAC, ensure that you start the agent and the ART processes with the Run As Administrator option.

Where can I find a list of ELM or IBM Rational product families that are supported by ART?

For a list of ELM or IBM Rational product families that are supported by ART, see technical document http://www.ibm.com/support/docview.wss?uid=swg21699136.

How do I enable debug logs in License Key Server Administration and Reporting Tool V8.1.5 or higher?

Perform the following steps to enable debug logs in License Key Server Administration and Reporting Tool V8.1.5 or higher:

Stop the License Key Server Administration and Reporting Tool.
Go to the installation folder (installation_location\servers\rcladmin\conf\rcladmin).
Note: Following are the default installation locations:
- For : C:\Program Files\IBM\ICL\RLKSAdmin
- For : /opt/IBM/ICL/RLKSAdmin
Edit the log4j2.xml file and change the property root level="error" from "error" to "DEBUG" or "TRACE" as required.
Start the License Key Server Administration and Reporting Tool.