Mapping functions of the software_instances REST API

Mapping software_instances REST API functions

The software_instances REST API allows you to retrieve information about software instances that were installed on the servers 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 not only substitutes 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 software instances that were installed on the servers that contributed to the peak in the utilization of a license metric by a product

• software_instances API allows you to retrieve information only about software instances that were installed on the servers that contributed to the peak of a license metric of a product over a reporting period.
• 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
  • 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 were installed on the servers that contributed to the peak
  • The overall utilization of a license metric of a product during the peak
  To retrieve information about software instances that were installed on servers 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 the hwm_peak_time parameter.

     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.