Retrieval of software inventory (v2)

Edit online

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

Resource information

Table 1. Resource information
Operation details Description
HTTP method GET
Request headers
Accept-Language (optional)
  • Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
  • Values: en-US (only English is supported)
Token
  • Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests.
  • Values: an alphanumeric string that is generated in License Metric Tool
Request format application/json
Response headers
Content-Type
  • Use: Specifies the content type of the response.
  • Values: application/json
Content-Language
  • Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language.
  • Values: en-US, …
Response payload Software Instances element
Response format application/json
Response codes

200 – OK

500 – “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 https://hostname:port/api/sam/v2/schemas/software_instance.json

Available columns

Table 2. Available columns
Column Description Displayed by default Type
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 Cloud Pak to which the software instance is assigned
   String
9.2.26 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 bundle_name Name of the FlexPoint offering or CloudPak 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
9.2.21 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
9.2.11 component_detailed_version Version of the component based on the highest SWID tag that caused its detection.   String
component_name Component name. ✓ String
component_publisher_name Component publisher.   String
component_release Component release number. ✓ String
computer_bigfix_id Identifier of the computer as defined in BigFix®. For disconnected computers, the value is undefined.   Numeric
computer_dns_name DNS of the computer.   String
computer_group_id Identifier of the License Metric Tool computer group to which the computer belongs. The value 0 represents the All Computers group.   Numeric
computer_id Identifier of the computer as defined in License Metric Tool.   Numeric
computer_ip_address IP address of the computer. ✓ String
computer_name Name of the computer. ✓ String
computer_os Operating system of the computer.   String
computer_os_type Type of the operating system of the computer.   String
9.2.25 disconnected_endpoint_id Identifier of the disconnected computer as defined in the config/endpoint_id.txt file in the disconnected scanner folder. For computers that do not report to a disconnected data source, the value is null.   String
discoverable_family_guid Component family GUID. For example, if the component is IBM DB2 Enterprise Server Edition, component family is IBM DB2.   String
discoverable_guid Component GUID.   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 under which the component is installed. ✓ String
discovery_start Date and time when the component was reported for the first time. The time is specified in the GMT time zone. ✓ String
exclusion_or_suppress_comment Comment that was provided during the exclusion or suppression.   String
instance_id Identifier of the component instance.   Numeric
9.2.14 is_charged Information whether the component to product assignment is charged.   Boolean
is_confirmed Information whether the assignment of the component to the product is confirmed.   Boolean
9.2.21 is_entitled Information whether you declared the particular product as your software entitlement.   Boolean
is_excluded Information whether the product is excluded from pricing calculations.   Boolean
is_present Information whether the component is still installed in the environment.   Boolean
is_suppressed Information whether the component is suppressed on the computer on which it is installed. ✓ Boolean
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
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
product_family_guid Product family GUID. For example, if the product release is IBM DB2 Enterprise Server Edition 10.5, product is IBM DB2 Enterprise Server Edition.
Note: Starting from application update 9.2.26, the column is deprecated and substituted with the product_guid column.
   String
9.2.26 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_name Name of the product to which the component is assigned. ✓ String
product_publisher_name Product publisher.   String
product_release Product release number. ✓ String
product_release_guid Product release GUID.   String
product_release_name Name of the product release to which the component is assigned.   String

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
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 within 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 https://hostname:port/api/sam/v2/software_instances
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"computer_name":"<name>",
"computer_ip_address":["<ip_address>"],
"component_name":"IBM Endpoint Manager 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":"IBM Endpoint Manager for Power Management",
"product_release":"9.0"
}]

Example conversation - all columns

Request
GET https://hostname:port/api/sam/v2/software_instances?columns[]=discovery_path
&columns[]=instance_id&columns[]=computer_id&columns[]=computer_bigfix_id
&columns[]=computer_dns_name&columns[]=computer_group_id&columns[]=computer_name
&columns[]=computer_ip_address&columns[]=computer_os&columns[]=computer_os_type
&columns[]=component_name&columns[]=component_release&columns[]=disconnected_endpoint_id
&columns[]=discoverable_guid&columns[]=component_publisher_name&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=columns=metric_code_name&columns[]=is_confirmed
&columns[]=is_excluded&columns[]=is_suppressed&columns[]=exclusion_or_suppress_comment
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"instance_id":1,
"computer_id":3,
"computer_bigfix_id":null,
"computer_dns_name":"<name>",
"computer_group_id":0,
"computer_name":"<name>",
"computer_ip_address":"<ip_address>",
"computer_os":"AIX 5.3",
"computer_os_type":"AIX",
"component_name":"IBM Endpoint Manager Platform Agent",
"component_release":"9.0",
"disconnected_endpoint_id":5,
"discoverable_guid":"0768FB15-383C-4124-A7E2-0D76DDA06874",
"component publisher name":"IBM",
"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":"IBM Endpoint Manager for Power Management",
"product_publisher_name":"IBM",
"product_release_name":"IBM Endpoint Manager 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 https://hostname:port/api/sam/v2/software_instances?columns[]=discovery_path
&columns[]=component_name&columns[]=product_name&columns[]=is_confirmed
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"component_name":"IBM Endpoint Manager Platform Agent",
"product_name":"IBM Endpoint Manager for Power Management",
"is_confirmed":0
}]

Example conversation - association

Request
GET https://hostname:port/api/sam/v2/software_instances
?columns[]=computer_id&columns[]=computer_health.catalog_version
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"computer_id":1,
"catalog_version":1304630
}]