Retrieval of software inventory (v2)

9.2.8 Available from 9.2.8. You use the GET operation on the api/sam/v2/software_instances element to request information about software installed in your infrastructure. The API returns details of existing components as well as historical data about components that were removed.

Permissions

User You must have the View Endpoints and View Hardware Inventory permissions to use this API.

Resource URL

https://hostname:port/api/sam/v2/software_instances?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.
Response payload Software Instances element
Response format application/json
Response codes

200 – OK

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

9.2.10 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/software_instance.json?token=<token>

Available columns

Table 2. Available columns
Column Description Displayed by default Type
instance_id Identifier of the component instance. Numeric
computer_id Identifier of the computer as defined in BigFix Inventory. Numeric
computer_bigfix_id Identifier of the computer as defined in BigFix. Numeric
computer_dns_name DNS of the computer. String
computer_name Name of the computer. ✓ String
computer_ip_address IP address of the computer. ✓ String
computer_os Operating system of the computer. String
computer_os_type Type of the operating system of the computer. String
component_name Component name. ✓ String
component_release Component release number. ✓ String
9.2.11 component_detailed_version Detailed version of a software component. The version is used as software signature. The software version is detected in several ways, such as in the presence of specific packages, the highest version of SWID tags, Windows file, and extended signature reporting. The package based discovery is available since BigFix Inventory . String
discoverable_guid Component GUID. String
discoverable_family_guid Component family GUID. For example, if the component is IBM DB2 Enterprise Server Edition, component family is IBM DB2. String
component_publisher_name Component publisher. String
component_has_usage Information whether usage data is available for the component. Boolean
is_present Information whether the component is still installed in the environment. Boolean
discovery_start Date and time when the component was reported for the first time. The time is specified in the GMT time zone. ✓ String
discovery_end Date and time when the component was reported for the last time. The time is specified in the GMT time zone. ✓ String
discovery_path Path where the component is installed. Starting from BigFix Inventory 10.0.2, discovery path is available for all products. ✓ String
product_name Name of the product to which the component is assigned. ✓ String
10.0.8 product_guid Product GUID. For example, if the product release is IBM DB2 Enterprise Server Edition 10.5, product is IBM DB2 Enterprise Server Edition. String
product_family_guid Product family GUID. For example, if the product is IBM DB2 Enterprise Server Edition, product family is IBM DB2. String
product_publisher_name Product publisher. String
product_release_name Name of the product release to which the component is assigned. String
product_release Product release number. ✓ String
product_release_guid Product release GUID. String
metric_id Identifier of the license metric that is used by the product. For information about the meaning of each metric_id, see: Metric IDs and code names. String
metric_code_name Unique code name of the license metric that is used by the product. For information about the meaning of each metric_code_name, see: Metric IDs and code names. String
is_confirmed Information whether the assignment of the component to the product is confirmed. Boolean
is_excluded Information whether the product is excluded from pricing calculations. Boolean
is_suppressed Information whether the component is suppressed on the computer on which it is installed. ✓ Boolean
exclusion_or_suppress_comment Comment that was provided during the exclusion or suppression. String
9.2.13 bundle_id Identifier of the FlexPoint offering or CloudPak to which the software instance is bundled. Possible values include:
  • - 1 - The software instance cannot be assigned to any FlexPoint offering nor Cloud Pak because the component is not assigned to any product
  • 0 - The software instance is not bundled to any FlexPoint offering nor Cloud Pak
  • Other values - Identifier of the FlexPoint offering or CloudPak to which the software instance is assigned
 String
9.2.13 bundle_name Name of the FlexPoint offering or Cloud Pak to which the software instance is assigned. Possible values include:
  • Empty column - The software instance cannot be assigned to any FlexPoint offering nor Cloud Pak because the component is not assigned to any product
  • None - The software instance is not bundled to any FlexPoint offering nor Cloud Pak
  • Other values - Name of the FlexPoint offering or Cloud Pak to which the software instance is assigned
 String
10.0.8 bundle_type Type of a bundle to which the software instance is assigned. Possible values include:
  • -1 - The software instance is not assigned to any bundle or cannot be assigned because the component is not assigned to any product
  • 0 - FlexPoint bundle
  • 1 - Cloud Pak bundle
 Numeric
10.0.8 bundle_guid GUID of the FlexPoint offering or Cloud Pak to which the software instance is assigned. Possible values include:
  • Empty column - The software instance is not bundled to any FlexPoint offering nor Cloud Pak
  • Other values - GUID of the FlexPoint offering or Cloud Pak to which the software instance is assigned
 String
9.2.13 is_vulnerable Information whether any Common Vulnerabilities and Exposures (CVE) are matched to the component. Possible values include:
  • 0 - No CVEs are matched
  • 1 - At least one CVE is matched
 Boolean
9.2.14 is_charged Information whether the component to product assignment is confirmed. Boolean
10.0.8 is_entitled Information whether you declared the particular product as your software entitlement. Boolean

Applicable associations

You can additionally retrieve data from the following associations:
Important: All associations provide data about items that currently exist in the infrastructure. For removed computers and uninstalled software, these associations return null.

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 release
URL?columns[]=product_name&columns[]=product_release
 String
order Specify how to sort the returned 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 computer ID descending
URL?order[]=computer_id 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
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>

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

Example: Retrieve software instances whose product name contains "BigFix" OR the discovery start is within a specific date range 
URL?criteria={ "or": [ ["product_name", "contains", "BigFix"], 
{ "and": [ ["discovery_start", ">", "2018-10-01T00:00:00+00:00Z"], 
["discovery_start", "<", "2018-10-02T00:00:00+00:00Z"] ] } ] }

For columns that use the date and time 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: Retrieve software instances which took part in the license utilization peak. The date and time of the peak is: 2018-10-10T00:00:00+00:00Z. Query searches for the instances that meet the following criteria: product name contains "DB2" AND use the given metric AND discovery start withing the peak.

For PVU, RVU MAPC and VPC
URL?criteria={ "and": [ ["discovery_start", "<=", "2018-10-10T00:00:00+00:00Z"], 
["discovery_end", ">", "2018-10-10T00:00:00+00:00Z"], ["product_name", "contains", "DB2"], ["metric_id", "=", "5"] ] }
For other metrics
URL?criteria={ "and": [ ["discovery_start", "<", "2018-10-11T00:00:00+00:00Z"], 
["discovery_end", ">=", "2018-10-10T00:00:00+00:00Z"], ["product_name", "contains", "DB2"], ["metric_id", "=", "9"] ] }
Example: Retrieve software instances that were first reported within the last 7 days
URL?criteria={"and":[["discovery_start","last","P7D"]]}
 String

Example conversation - default columns

Request
GET api/sam/v2/software_instances?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"computer_name":"NC107069",
"computer_ip_address":["10.0.107.69"],
"component_name":"BigFix Platform Agent",
"component_release":"9.0",
"is_present":1,
"discovery_start":"2016-04-28T15:37:26Z",
"discovery_end":"2016-11-17T15:11:10Z",
"discovery_path":"/opt/BESClient/bin/properties/version",
"product_name":"BigFix for Power Management",
"product_release":"9.0"
}]

Example conversation - all columns

Request
GET api/sam/v2/software_instances?columns[]=discovery_path
&columns[]=instance_id&columns[]=computer_id&columns[]=computer_bigfix_id
&columns[]=computer_dns_name&columns[]&columns[]=computer_name
&columns[]=computer_ip_address&columns[]=computer_os&columns[]=computer_os_type
&columns[]=component_name&columns[]=component_release&columns[]=discoverable_guid
&columns[]=component_publisher_name&columns[]=component_has_usage&columns[]=is_present
&columns[]=discovery_start&columns[]=discovery_end&columns[]=product_name
&columns[]=product_publisher_name&columns[]=product_release_name&columns[]=product_release
&columns[]=metric_id&columns=metric_code_name&columns[]=is_confirmed
&columns[]=is_excluded&columns[]=is_suppressed&columns[]=exclusion_or_suppress_comment
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"instance_id":1,
"computer_id":3,
"computer_bigfix_id":null,
"computer_dns_name":"NC107069",
"computer_name":"NC107069",
"computer_ip_address":"10.0.107.69",
"computer_os":"AIX 5.3",
"computer_os_type":"AIX",
"component_name":"BigFix Platform Agent",
"component_release":"9.0",
"discoverable_guid":"0768FB15-383C-4124-A7E2-0D76DDA06874",
"component publisher name":"IBM",

"component_has_usage":1,
"is_present":0,
"discovery_start":"2016-04-28T15:37:26Z",
"discovery_end":"2016-11-17T15:11:10Z",
"discovery_path":"/opt/BESClient/bin/properties/version",
"product_name":"BigFix for Power Management",
"product_publisher_name":"IBM",
"product_release_name":"BigFix for Power Management",
"product_release":"9.0",
"metric_id":"6",
"metric_code_name":"INTERNAL_RVU_MAPC",
"is_confirmed":0,
"is_excluded":0,
"is_suppressed":0,
"exclusion_or_suppress_comment":null
}]

Example conversation - additional column

Request
GET api/sam/v2/software_instances?columns[]=component_name
&columns[]=product_name&columns[]=is_confirmed
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
  "component_name":"BigFix Platform Agent",
  "product_name":"BigFix for Power Management",
"is_confirmed":0
}]

Example conversation - association

Request
GET api/sam/v2/software_instances?columns[]=computer_id
&columns[]=computer_health.catalog_version
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"computer_id":1,
"catalog_version":1304630
}]