Retrieval of license metric utilization (v2)

9.2.10 Available from 9.2.10. Use the GET operation on the api/sam/v2/license_usage element to request information about utilization of license metrics by products that are installed in your infrastructure. By default, the results are returned for the computer group of the user whose token is used for authentication and cover the period for which data is aggregated in this group. They also include custom fields that were added to the All Metrics report.

Permissions

User You must have the View License Metrics permission to use this API.

Resource URL

https://hostname:port/api/sam/v2/license_usage?token=token

Resource information

Table 1. Resource information
Operation details Description
HTTP method GET
Request headers
Header
Accept-Language (optional)
Values
en-US (only English is supported)

Negotiates the language of the response. If the header is not specified, the content is returned in the server language.
Request format application/json
Response headers
Header
Content-Type
Values
application/json

Specifies the content type of the response.
Header
Content-Language
Values
en-US, …

Specifies the language of the response content. If the header is not specified, the content is returned in the server language.
Header
startdate
Values
YYYY-MM-DD

Specifies the date starting from which the data is retrieved.

Header
enddate
Values
YYYY-MM-DD

Specifies the date until which the data is retrieved.

Header
computerGroupId
Values
Integer

Specifies ID of the computer group for which data is retrieved.

Response payload License Usage element
Response format application/json
Response codes

200 – OK

400 – "Bad Request" if a query parameter contains errors or is missing

Schema description

To retrieve the list of all columns that are returned by this REST API together with their descriptions, use the following request.
GET api/sam/v2/schemas/license_usage.json?token=token

Available columns

Table 2. Available columns
Column Description Displayed by default Type
product_publisher_name Name of the product publisher. ✓ String
product_id Identifier of the software product. Integer
product_name Name of the software product. ✓ String
product_family_guid GUID of the software product. String
metric_id Identifier of the license metric. For explanation of the returned values, see: Metric IDs and code names. String
metric_name Name of the license metric. The value that is returned by the metric_name parameter is provided as reference and can slightly differ from the value that is provided as a metric description in Metric ID, code name, and description. It is best to retrieve metrics by using metric_id or metric_code_name parameters and then check the exact metric description by referring to Metric ID, code name, and description. String
metric_code_name Code name of the license metric. For explanation of the returned values, see: Metric IDs and code names. ✓ String
hwm_quantity The highest number of metric units that the product used within the period for which the data is retrieved. When metric quantity is not measured for a particular license metric, the value returned by the hwm_quantity parameter is -1. The value -1 cannot be used for sorting nor filtering. ✓ Integer
threshold The maximum number of metric units that the product is entitled to use within a computer group. The value is set manually and is used to calculate the metric threshold delta. Integer
threshold_delta It is calculated by subtracting metric quantity from the threshold. When you specify a threshold for a license metric that is not calculated, the value returned by the threshold_delta parameter is 2147483647. The value 2147483647 cannot be used for sorting nor filtering. Integer
imported_part_numbers Part number that was imported to BigFix Inventory. It represents the product that is listed in the product_name column and its license metric. String
is_reaggregation_needed Specifies whether recalculation is needed for the product. The parameter cannot be used to filter or sort the results. Boolean
custom_field_number Custom field that was added to the All Metrics report. To view the list of all custom fields, view the license_usage.json schema. Various
9.2.14 hwm_peak_time The date and time when the highest number of metric units was used by a product in the selected period of time. If the value of hwm_quantity parameter is -1, the value of hwm_peak_time is meaningless.
Note: Retrieving hwm_peak_time might noticeably increase the time of retrieving the data.
 String
10.0.1 bundle_id ID of the Cloud Pak or FlexPoint Bundle to which the product is assigned. Integer
10.0.1 bundle_name Name of the Cloud Pak or FlexPoint Bundle to which the product is assigned. String
10.0.1 bundle_type Type of the bundle. Possible values:
  • -1 - Not a bundle
  • 0 - FlexPoint bundle
  • 1 - Cloud Pak
 Set of integers
10.0.1 bundle_guid GUID of the Cloud Pak or FlexPoint Bundle to which the product is assigned. String
10.0.1bundle_metric_contribution When the product is a part of a Cloud Pak or FlexPoint Bundle, the column shows the number of license metric units that the particular product contributes to the overall metric quantity of the Cloud Pak or FlexPoint Bundle to which that product is assigned.

It is the value from the hwm_quantity column multiplied by the conversion option that is specified for the particular product.

When the product is not a part of the Cloud Pak or FlexPoint Bundle, the column is empty.

 Integer
10.0.9 product_bundle_ratio_divider When the product is a part of a Cloud Pak or FlexPoint Bundle, the column shows the divider of the ratio that is used to convert product license metrics to license metrics of the bundle.

For example, when IBM Security QRadar SOAR Users is installed as part of IBM Cloud Pak for Security, the conversion ratio is 5:1. The value of the product_bundle_ratio_divider column in this case would be 5.

 Integer
10.0.9 product_bundle_ratio_factor When the product is a part of a Cloud Pak or FlexPoint Bundle, the column shows the factor of the ratio that is used to convert product license metrics to license metrics of the bundle.

For example, when IBM Security QRadar SOAR Users is installed as part of IBM Cloud Pak for Security, the conversion ratio is 5:1. The value of the product_bundle_ratio_factor column in this case would be 1.

 Integer

Query parameters

Table 3. Query parameters
Parameter Description Required Value
columns Specify which columns to retrieve. If you do not specify this parameter, only default columns are retrieved.
Example: Retrieve product name and threshold delta
URL?columns[]=product_name&columns[]=threshold_delta
 String
computerGroupId Specify ID of the computer group for which you want to retrieve the data. If you do not specify this parameter, the data is retrieved for the computer group of the user whose token is used for authentication. If you specify the parameter, you can retrieve the data for a subgroup of this computer group.

To view IDs of computer groups, log in to BigFix Inventory and go to Reports > Computer Groups. Then, hover of the Manage Report View icon Manage Report View icon, click Configure View, and select the ID column to display it on the report.

Example: Retrieve data for computer group 5
URL?computerGroupId=5
 Integer
order Specify how to sort the retrieved data. The default direction for sorting columns is ascending. If you want to specify a descending sort, append desc to the column name.
Example: Order by threshold delta
URL?order[]=threshold_delta desc
 Alphanumeric
limit Specify the number of rows to retrieve. If you omit this parameter, all rows are retrieved.
Example: Retrieve 100 records 
URL?limit=100
 Numeric
offset Specify the number of rows to skip for retrieving results. You can use it together with the limit parameter to paginate results.
Example: Retrieve 50 records starting after record 150
URL?limit=50&offset=150
 Numeric
startdate Specify the date starting from which you want to retrieve the data. Specify it in the YYYY-MM-DD format. If you do not specify the filter, its default value is the date of the last successful import of data to BigFix Inventory minus the number of days for which data is calculated in the computer group (90 days by default).
Example: Retrieve data starting from 14th July 2017
URL?startdate=2017-07-14
 Date
enddate Specify the date until which you want to retrieve the data. Specify it in the YYYY-MM-DD format. If you do not specify the filter, its default value is the date of the last successful import of data to BigFix Inventory.
Example: Retrieve data from 1st October 2017 to 31st October 2017
URL?startdate=2017-10-01&enddate=2017-10-31
 Date
token A unique user authentication identifier. You can retrieve it by using REST API for retrieving authentication token. You can also log in to BigFix Inventory, hover over the User icon User icon, and click Profile. Then, click Show token. ✓ Alphanumeric
criteria Retrieve records which match specific conditions. The parameter should have the following structure, written in one line: 
<criteria> ::= <left-brace> <boolean-operator> <colon> <left-bracket> 
<criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace>
<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> ::= <json-array> | <json-string> | <json-number> | <json-null>
Note: The license_usage REST API does not support nested filtering criteria.
Example 1: Retrieve software instances whose product name contains "BigFix" AND the threshold delta is below 0
URL?criteria={"and":[["product_name","contains","BigFix"],
["threshold_delta","<","0"] ] }

In case of the threshold, and custom_field_number fields, you can retrieve all entries for which the value is specified or for which it is not specified.

Example 2: Retrieve software products for which the threshold is specified
URL?criteria={"and":[["threshold","!=",]]}
Example 3: Retrieve software products for which the threshold is not specified
URL?criteria={"and":[["threshold","=",]]}

If you created custom fields that use the date values, you can retrieve data also for a period instead of a specific date. To do so, use last or next as <operator>, and then specify the time value in the following convention: PxD/PxW/PxM/PxY, where x is a number in the 1-999 range, and D, W, M, or Y is a designator that represents days, weeks, months, or years respectively.

Example 4: Retrieve software products for which entitlement ends within next month
URL?criteria={"and":[["custom_field_1","next","P1M"]]}

For more information about operators, see: Common connectors and operators.

 String

Example conversation - default columns

Request
GET api/sam/v2/license_usage?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response header
Status Code: 200 OK
Content-Type: application/json
computerGroupId: 0
enddate: 2017-10-31
startdate: 2017-10-01
Response body
[{

"product_publisher_name": "IBM",
"product_name": "WebSphere Service Registry and Repository",
"metric_code_name": "PVU_FULL_CAP",
"hwm_quantity": 480
}]

Example conversation - all columns

Request
GET api/sam/v2/license_usage?columns[]=product_id
&columns[]=product_name&columns[]=product_family_guid&columns[]=metric_id
&columns[]=metric_name&columns[]=metric_code_name&columns[]=hwm_quantity
&columns[]=threshold&columns[]=threshold_delta&columns[]=imported_part_numbers
&columns[]=is_reaggregation_needed&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{

"product_publisher_name": "IBM",
"product_id": 29258,
"product_name": "WebSphere Service Registry and Repository",
"product_family_guid": "3b31a72e-468d-47bb-825a-ea26c8e85199",
"metric_id": 3,
"metric_code_name": "PVU_FULL_CAP",
"metric_name": "PVU Full Capacity",
"hwm_quantity": 480,
"threshold": null,
"threshold_delta": null,
"imported_part_numbers": null,
"is_reaggregation_needed": 0
"bundle_name": null, 
"bundle_type": -1,
"bundle_guid": null,
"bundle_metric_contribution": null
}]

Example conversation - additional column

Request
GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=metric_name&columns[]=threshold_delta
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"product_name": "WebSphere Service Registry and Repository",
"metric_name": "PVU Full Capacity",
"threshold_delta": 100
}]

Example conversation - custom field

To retrieve data from custom fields that were added to the All Metrics report, start by viewing the license_usage.json schema. The schema lists all columns, including custom fields. Identify the custom field from which you want to retrieve the data.
Request - check list of created custom fields
GET api/sam/v2/schemas/license_usage.json?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Response - list of all columns, including custom fields
[{
"product_name":
      {
       "type": "string",
       "description": "Name of the software product."
       },
...

"custom_field_1":
       {
       "type": "date",
       "title": "Entitlement End"
       }
}]
After you identify the name of the custom field, you can use it in the REST API request.
Request
GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=custom_field_1&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"product_name": "WebSphere Service Registry and Repository",
"custom_field_1": "2017-10-01"
}]

Example conversation - retrieving information about Cloud Pak or FlexPoint Bundle

Request
GET api/sam/v2/license_usages?columns[]=product_name
&columns[]=bundle_name&columns[]=bundle_type&columns[]=bundle_metric_contribution
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623&criteria={"and":[["bundle_type","in","[0,1]"]]}
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"product_name": "IBM WebSphere Application Server Network Deployment",
"bundle_name": "IBM Cloud Pak for Applications"
"bundle_type": "1"
"bundle_metric_contribution": "100"
}]