Determining license usage for all computer systems

You can extract your data in bulk to determine total license usage for software on all your computer systems. Instead of using reports in the application user interface, you can make API requests to quickly retrieve large amounts of data.

Before you begin

Each API request must be authenticated with the token parameter. 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 , and click Profile. Then, click Show token.
To obtain the list of query parameters to narrow down your results and the list of available columns, see the information related to a particular API type.

Performance considerations

Retrieving large amounts of data might impact the performance of your environment, therefore API should not be used together with other performance intensive tasks, like data imports. For more information, see REST API considerations.
Retrieve your data in pages rather then query for each computer ID separately. You can make several API requests and use the limit and offset parameters to paginate your results.
Note:
- For environments with approximately 200 000 endpoints, it is recommended to retrieve your data in pages of 100 000 rows for computer systems, 200 000 rows for software instances, and 300 000 rows for license usage. If you limit the first request to 100 000 results, append the next request with the offset=100000 parameter to omit the already retrieved records. Adjust the values according to the size of your deployment.
- If you have a small number of endpoints, you can omit the limit and offset parameters, and retrieve your data by using only one API request.

Procedure

Retrieve the list of your computer systems:

https://hostname:port/api/sam/computer_systems?
token=token&limit=100000&offset=100000

Result: Each computer system has a different id. You can later use this id to create a match between your software instances and computer systems.

{
    "id": 182,
    "parent_id": 175,
    "type": "virtual",
    "os": "Win2008R2 6.1.7601",
    "host_name": "NC9128109187",
    "dns_name": "NC9128109187",
    "ip_address": [
        "9.128.109.187"],
    "last_seen": "2014-06-06T03:56:39Z",
    "hardware_manufacturer": "-",
    "hardware_model": "-",
    "hardware_serial_number": "TLM_VM_4236ac43",
    "processor_type": "Multi-core",
    "processor_brand": "Xeon(R), 3 or 4 Socket",
    "processor_vendor": "Intel(R)",
    "processor_model": "E3-12xx, E7-28xx, E7-48xx",
    "partition_cores": "1.0",
    "server_processors": 1,
    "server_cores": 1

}

Retrieve the list of your software instances. The software_title_name column that allows you to recognize the name of your software is hidden by default, which means that you have to append the URL with the columns[] parameter followed by the name of a hidden column.
The following example retrieves the computer_system_id and software_title_name columns so that you can recognize which software is installed on which computer system. If you want to retrieve complete information, append the URL with the names of all columns. You can find the column names in response body:
```
https://hostname:port/api/sam/software_instances?
token=token&limit=100000&offset=100000&
columns[]=computer_system_id&columns[]=catalog_dimension.software_title_name
```
Result: Each software instance contains a computer_system_id column that represents an ID of a computer that a particular instance is installed on. Use this column to match your software instances with computer systems. For example, if rows 152-155 contain a computer_system_id=182 column, it means that all those software instances are installed on a computer system with ID 182.
```
{
    "computer_system_id": 182,
    "catalog_dimension": {
        "software_title_name": "BigFix Inventory"
    }
```
Retrieve the license usage information. Append the URL with the software_title_dimension.name column to be able to recognize the name of the software that the license usage is presented for.
The following example retrieves the computer_system_id, metric_name, peak_value, and software_title_dimension.name columns. If you want to retrieve complete information, append the URL with the names of all columns. You can find the column names in response body:
```
https://hostname:port/api/sam/license_usages?
token=token&limit=100000&offset=100000&
columns[]=computer_system_id&columns[]=metric_name&columns[]=peak_value&
columns[]=software_title_dimension.name
```
Result: Each record contains a computer_system_id column that represents an ID of a computer for which the license usage is calculated. Use this column to match the license usage with computer systems. For example, if rows 152-155 contain a computer_system_id=182 column, it means that all those license usage records are presented for a computer system with ID 182. The peak_value column represents the peak license usage (over last 90 days) for a particular software title (which is described by software_title_dimension.name). The metric_name column allows you to recognize whether the license type is PVU or RVU, full or subcapacity.
```
{
    "computer_system_id": 182,
    "metric_name": "RVU_FULL_CAP",
    "peak_value": 2,
    "software_title_dimension": {
        "name": "BigFix Inventory"
}},

{
    "computer_system_id": 182,
    "metric_name": "RVU_SUB_CAP",
    "peak_value": 2,
    "software_title_dimension": {
        "name": "BigFix Inventory"
}}
```
Determine the total license usage for a software title by summing up the values of all peak_value columns retrieved for this software title from all your computer systems. For example, sum up all peak_values for BigFix Inventory on all computer systems that contain entries for this particular software. Do not combine the metric types, but calculate the PVU_FULL_CAP, RVU_FULL_CAP, PVU_SUB_CAP, and RVU_SUB_CAP separately.