Creating a report definition

Use License Key Server Administration and Reporting Tool to evaluate and track license usage for the IBM® Engineering Lifecycle Management (ELM) or IBM Rational® products that are used in your organization.

About this task

Use the web client to create the report definition to define the parameters that specify the information that a report presents.

Note: If your license server log file contains product names that are logged in Japanese and you try to run token reports for 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.

Procedure

  1. Go to https://Hostname:4743/rcladmin, and log in using the login credentials that you used for adding the license server.

    If prompted to confirm the server and server administration application collaboration, click Yes.

  2. Click Reports and Create a report definition.
  3. Name the report and add a brief description.
  4. On the Parameters tab, select a license server to display the list of products that the server manages. You can select multiple servers to list more products for the report.
  5. Select the product or products from the list to be included in the report.
  6. Select a metric type for the report.

    The metric type lists the different artifacts of a license that can help you evaluate and track the licenses of various products that are used in your organization. License usage is computed in terms of license hours. License hours are calculated based on the product that is associated with a license and the duration for which it is used. For example, a report might provide information about license hours: 1 license used for 1 hour = 1 license hour.

    The following are the supported metrics types:
    • User count: IBM Common Licensing version 8.1.5.6 introduces a new metric called User count. This metric applies to products that use token-based licenses and enables you to generate a report about users. The User count metric represents the total number of users who used the products on a specific date and day for a selected duration.
      The report for this metric provides the following details in tabular format:
      • Date
      • Day of week
      • Number of users who used the products on a specific day
      The criteria used for calculating the number of users for a User count report are as follows:
      1. A user can use a product multiple times a day. All those occurrences are counted as one user.
      2. A user can use a product from one or more hosts or computers in a day. All those occurrences are counted as one user.
      3. Two or more users who use a product multiple times a day, from one or more machines, whose user names differ only in case can be counted as one or more users based on your preference.
      4. Two or more users who use a product multiple times a day, from one or more machines, whose user names are completely different are counted as separate users.
      5. A user who uses a ELM product multiple times a day with different roles, is counted as many times as the number of roles.
      6. The User count metric applies to token usage only.
      7. The User count metric is computed on a daily basis. No other duration is allowed.

      Here is an example user count report:

      Example available licenses report


    • License Details: This metric enables you to generate a report where you can view all key characteristics of licenses that belong to a product. This information is sourced from the license files that the license server currently uses. The report for this metric provides the following details:
      • License server name
      • Product name
      • License type and version
      • License issue date, which is the date on which the license was generated at LKC
      • License expiry date, which is the date after which you cannot use the license
      • Number of licenses currently deployed on the server
      • Number of tokens checked-out for each license
      The License Details metric is categorized into two sections - Summary and Details. Both sections are displayed as two separate tables. The Summary section lists generic information that applies to all different license definitions that belong to a product. This section includes the following information:
      • Product name
      • License server name
      • License type
      • Number of licenses currently deployed on the server
      • Number of tokens checked-out for each license of the product

      The following example shows the Summary section of the License Details metric:

      Example License Details report


      The Details section of the License Details metric represents information that differs from one license definition to another. This section includes the following information:
      • License issue date, which is the date on which the license was generated at LKC
      • License expiry date, which is the date after which the license cannot be used
      • License version
      • License quantity
      • Number of tokens checked-out for the license

      The Details section of the information is in a separate table below the first table.

      The following example shows the Details section of the License Details metric:

      Example License Details report

      In the second table, the license file contains six different INCREMENT or definition lines for the tokens as a license. Each INCREMENT has mutually exclusive properties of dates, version, and quantity.
      Tip: Initially the second table is empty. When you select a record in the first table, you can see corresponding records in the second table.
      A License Details metric report does not include the following information:
      1. The report does not retrieve any information from the license server. It only uses the one-time and unmodifiable information from the license files that are used on the server.
      2. If you start or restart the license server using a license file that is not configured in the License Key Server Administration Agent, duplicate information might occur for some licenses in the License Details report.
      3. The report does not display the relationship among suite-based licenses.


    • Chargeback: This metric represents a simple chargeback policy for product licenses that are used in an organization. The report for this metric is like an invoice, where the number of licenses that are used by each user during a specified time is listed. The number of license hours is multiplied by the unit costs that are associated with each license hour of that kind of license for that product. This product gives the value in currency to be charged for that user.
      • LDAP chargeback groups: You can create a chargeback report that is based on groups in LDAP. To create a chargeback report definition that is based on groups in LDAP, first you must create a LDAP `chargeback group. Then, on the Chargeback Groups tab, select the group or groups you want to include in the report.
      • Custom chargeback groups: You can run chargeback reports based on groups that you created by using a file that contains the group details. First, create a custom chargeback group. Then, on the Chargeback Groups tab, select the group or groups you want to include in the report.
      Note: When you create or modify chargeback groups in License Key Server Administration and Reporting Tool, the reports contain all of the data that has been created since you created or modified the chargeback groups. For example, if you create a group on January 1 at 9:00 am, the report contains license usage data starting January 1 at 9:00 am and onwards. For more information, see the technical note.

      The report contains data that is aggregated at two levels: group-based and product-based. To retrieve the user level chargeback data, you must export the report data. You can export the report at the group, product, or user level. The emails that are sent according to the schedule contain report data for all levels (group, product, and user).

      Here is an example group-based chargeback report:

      Example group-based chargeback report


    • Concurrent peak usage: This metric represents the maximum number of concurrent licenses that the selected license servers granted for the selected products. Prior to the 8.1.4.7 release, this metric was named Peak usage. Only the metric name was changed. What the metric represents was not changed.

      Here is an example concurrent peak usage report without ELM roles:

      Example concurrent peak usage report without ELM roles


      In the above example, at 9 AM on 31 August 2019, concurrent peak usage for IBM Programming Patterns is 48 tokens and for IBM Rational ClearQuest®, it is 55 tokens.

      Example concurrent peak usage report without ELM roles


      In the token's concurrent peak usage example above, peak usage for tokens in the third quarter of 2019 is 105.
      Important: The token's peak usage value is not derived from addition of other product's peak usage values. Similar to other products, the token is also captured based on the peak consumption on any day in the month of September.
      Attention: If you want the peak usage of tokens, you must select the license types as Floating - License Key Server.

      Here is an example concurrent peak usage report that contains ELM roles:

      Example concurrent peak usage report that contains ELM roles


    • User-based: This metric represents the product usage by a user from a license server at a specified time. This list includes the user and the host server name for the selected products for the specified duration.

      Here is an example user-based report without ELM roles:

      Example user-based report without ELM roles


      Here is an example user-based report that contains ELM roles:

      Example user-based report that contains ELM roles


    • User-based metrics for ELM authorized user license type: For more information, see Running Jazz authorized user licenses reports.


    • Token Value: Starting in V8.1.5 release, the token value is an available metric type for reporting. This metric represents token usage and product usage hours (in license hours) for the specified duration. The list includes user name, product name, token count for the product, and product usage hours for the specified duration. This report also includes a summary section which represents total product usage, total token count, and number of unique users for the report.

      Here is an example token value report in V8.1.5:

      Example token value report in V8.1.5


      Each record shows the product usage and corresponding token count for each user-product combination. If you use a ELM product with multiple roles, the License Key Server Administration and Reporting Tool consolidates all the product usage for that product. It displays the product usage as a single record and the token count shows the maximum token value that you have used for the product.

      For License Key Server V8.1.5.1 the Token Value report have same features as V8.1.5 with details on the modifications. Starting in License Key Server V8.1.5.1 the Token Value report have same features as V8.1.5 with an additional list for roles.

      Here is an example token value report in V8.1.5.1:

      Example token value report in V8.1.5.1


      Each record shows the product usage and corresponding token count for each user-product-role combination. The Role column is blank for records where the product is not a ELM product. For earlier releases of ELM product versions where the role name is not present, License Key Server Administration and Reporting Tool shows the default token count and role name according to the below mapping:

      Product Name Role Token Count
      IBM Engineering Workflow Management Developer-IEP 9
      IBM Engineering Lifecycle Optimization - Engineering Insights User 7
      IBM Engineering Test Management Quality Professional 10
      Engineering Insights User 7
      IBM Engineering Requirements Management DOORS® Next Analyst 9
      IBM Engineering Test Management Quality Professional 10
      IBM Engineering Systems Design Rhapsody® - Design Manager Contributor 5
      IBM Rational Software Architect Contributor 5
      IBM Engineering Workflow Management Developer-IEP 9
      IBM Engineering Requirements Management DOORS Next Analyst 9
  7. For ELM products only, click the Report based on ELM roles option to report on license usage by ELM roles.

    ELM-role-based reports are available only for RM, QM, CCM, and Design Manager applications in ELM. You can select both ELM and non-ELM products for one report. However, the role-based report shows only the data for the ELM products.

    Table 1. Metrics and license types that are supported for ELM-role-based reports.
    Metric Floating licenses Token licenses Authorized licenses
    Concurrent peak denial X
    Concurrent peak usage X
    User-based
  8. Run the report and save it.
    On the Reports page, the report is saved in a table that contains the following information:
    • Name
    • Metric
    • Creation date
    • Time last modified
    Note: If the License Key Server Administration Agent 8.1.4 is stopped while the reporting function is in progress, you must restore the reporting function. See the License Key Server Administration Agent stopped when reporting is in progress technical document. You must complete the steps only if you are using 8.1.4.

    If a message indicates that the report shows only a subset of information, try another set of parameters to improve the data that the chart presents. For steps, see the Out-Of-Box reports in License Key Server Administration and Reporting Tool might show a subset of information for large volumes of data technical document.

  9. Use the column headers to sort the data in the report table.

What to do next

Based on the report definition that you created, generate a report of your choice.

Feedback