Mapping functions of the software_instances REST API

9.2.14 Available from 9.2.14. If you have custom tools or internal processes that use the software_instances REST API, learn how to achieve your goals by using the v2/license_usage and v2/software_instances REST API. It is best to adjust the tools to use REST API in version 2.

Mapping software_instances REST API functions

The software_instances REST API allows you to retrieve information about the software instance that contributed to the peak in the utilization of a license metric by a product during the reporting period. By default, the reporting period is set to 90 days.

The v2/software_instances REST API allows you to retrieve information about all software instances in your environment. Additionally, you can retrieve data from any relevant period, including the details of existing components as well as historical data about components that were removed. By filtering the data you can narrow down the results to the instances that contributed to the peak in the utilization of a license metric by a product. Combining the capabilities of v2/license_usage and v2/software_instances APIs can not only substitute all functions of the old version of software_instances API, but also guarantees flexibility that allows you to alter the queries and retrieve the required data sample.

Examples

Scenario: Retrieving information about the software instances that contributed to the peak in the utilization of a license metric by a product

  • software_instances API allows you to only retrieve information about the software instances that contributed to the peak of a license metric of a product over a reporting period.
    Figure 1. Software instances that can be retrieved with the software_instances REST API

    The screen shows the chart representing the software instances that are reported by the software_instances REST API
  • v2/license_usage and v2/software_instances APIs allow you to retrieve the following information:
    • The list of all software instances that were used within a specified period
      Figure 2. Software instances that can be retrieved with the v2/software_instances REST API

      The screen shows the chart representing the software instances that are reported by the v2/software_instances REST API
    • The time of the peak in the utilization of a license metric by a product with the hwm_peak_time parameter value
    • The list of software instances that contributed to the peak
    • The overall utilization of a license metric of a product during the peak
    To retrieve information about the software instances that contributed to the peak in the utilization of a license metric by a product proceed with the following steps.
    1. Run the v2/license_usage REST API for a product and the license metric that is assigned to this product.

      Example

      GET api/sam/v2/license_usage?columns[]=product_name&columns[]=metric_code_name&columns[]=hwm_quantity&
columns[]=hwm_peak_time&criteria={"and":[["product_name","=","IBM DB2 Advanced Enterprise Server Edition PVU Option"]]}
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
    2. See the value of the hwm_peak_time column for the product-license pair in the response.

      Example

      [{
"product_name": "IBM DB2 Advanced Enterprise Server Edition PVU Option",
"metric_code_name": "PVU_SUB_CAP",
"hwm_quantity": 960,
"hwm_peak_time": "2018-10-11T01:12:26Z"
}]
    3. Run the v2/software_instances REST API with the filter on the following columns: Discovery Start and Discovery End. Base the dates on the value of hwm_peak_time.

      Example

      GET api/sam/v2/software_instances?columns[]=discovery_start&columns[]=discovery_end&columns[]=product_name&
columns[]=metric_id&columns[]=computer_name&criteria={"and":[["product_name","=
","IBM DB2 Advanced Enterprise Server Edition PVU Option"],["metric_id","=","5"],["discovery_start", "<=", "2018-10-11T01:12:26Z"], 
["discovery_end", ">", "2018-10-11T01:12:26Z"]]}&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
      Note: The example uses the timestamp format used for PVU, RVP MPAC and VPC metrics. For different metrics, see: Retrieval of software inventory (v2).
    4. See the results for a list of software instances that contributed to the peak.