Classifying software (v2)
Available from 9.2.14. You can use the
PUT
operation on the api/sam/v2/software_instances
element to define, change, or
migrate software classification.
The API supports the following actions
- Assigning component instance to a product using relation existing in a catalog
- Assigning component instance to a product using custom bundling. The bundling needs to be created earlier in WebUI.
- Excluding products from metric calculation and clearing the exclusion
- Suppressing component from inventory and clearing the suppression
Assigning a product to a FlexPoint offering or a Cloud Pak
Assigning a component to a product and product to a Cloud Pak in one call
Permissions
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
Operation details | Description |
---|---|
HTTP method | PUT |
Request headers |
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 |
Specifies the content type of the response. |
Specifies the language of the response content. If the header is not specified, the content is returned in the server language. |
|
Response payload | n/a element |
Response format | application/json |
Response codes |
|
Parameters
- token
- is_charged
- metric_id
- product_release_guid
- instance_id, or, alternatively, a combination of parameters including: a parameter that identifies a computer: computer_dns_name or computer_bigfix_id and a parameter that identifies software: discoverable_guid that can be followed by the discovery_path parameter for precision.
Parameter | Description | Type |
---|---|---|
instance_id | Identifier of the component instance. | Numeric |
computer_bigfix_id | Identifier of the computer as defined in BigFix. | Numeric |
computer_dns_name | DNS of the computer. | String |
discoverable_guid | Component GUID. | String |
discovery_path | Path under which the component is installed. Available for
BigFix products only. For non-BigFix products, the returned value is
null . |
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 |
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 |
![]() |
Information whether the component to product assignment is charged. | Boolean |
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 ![]() |
Alphanumeric |
verbose | Descriptive information about the result of an API request. By default, this parameter is set to false. | Boolean |
simulate | By adding this parameter to API request you can test the call to view its results and status. By default, this parameter is set to false. | Boolean |
Example conversation
- Assigning a component
Assign a component instance with ID 214 to a product release with GUID 7E9162CD-B894-48B3-AFB7-1234567890AB using bundling with metric with ID 6 which has charged type as '0'.
- Request
-
PUT https://example.com:9081/api/sam/v2/software_instances?token=1234567890abcdef1234567890abcdef12345678 Content-Type: application/json { "rows": [ { "instance_id": 214, "product_release_guid": "7E9162CD-B894-48B3-AFB7-1234567890AB", "metric_id": 6, "is_charged": 0 } ] }
- Response body
-
Response code: 207 Content-Type: application/json; charset=utf-8 { "valid_instances": { "Bundled": 1 }, "invalid_instances": {}, "unmodified_instances": 0 }
- Suppress a component instance with ID 103 from BigFix Inventory.
- Request
-
PUT https://example.com:9081/api/sam/v2/software_instances?token=1234567890abcdef1234567890abcdef12345678 Content-Type: application/json { "rows": [ { "instance_id": 103, "is_suppressed": 1 } ] }
- Response
-
Response code: 207 Content-Type: application/json; charset=utf-8 { "valid_instances": { "Suppressed": 1 }, "invalid_instances": {}, "unmodified_instances": 0 }
- Clear suppression of a component instance with ID 73
- Request
-
PUT https://example.com:9081/api/sam/v2/software_instances?token=1234567890abcdef1234567890abcdef12345678 Content-Type: application/json { "rows": [ { "instance_id": 73, "is_suppressed": 0 } ] }
- Response
-
Response code: 207 Content-Type: application/json; charset=utf-8 { "valid_instances": { "Unsuppressed": 1 }, "invalid_instances": {}, "unmodified_instances": 0 }
- Exclude product assigned to component instance with ID 94 from metric calculation
- Request
-
PUT https://example.com:9081/api/sam/v2/software_instances?token=1234567890abcdef1234567890abcdef12345678 Content-Type: application/json { "rows": [ { "instance_id": 94, "is_excluded": 1 } ] }
- Response
-
Response code: 207 Content-Type: application/json; charset=utf-8 { "valid_instances": { "Excluded": 1 }, "invalid_instances": {}, "unmodified_instances": 0 }
- Clear exclusion of a product assigned to component instance with ID 58
- Request
-
PUT https://example.com:9081/api/sam/v2/software_instances?token=1234567890abcdef1234567890abcdef12345678 Content-Type: application/json { "rows": [ { "instance_id": 58, "is_excluded": 0 } ] }
- Response
-
Response code: 207 Content-Type: application/json; charset=utf-8 { "valid_instances": { "Included": 1 }, "invalid_instances": {}, "unmodified_instances": 0 }
Assigning a product to a FlexPoint offering or a Cloud Pak
- instance_id or a combination of fields that includes:
- A field that identifies a computer: computer_dns_name or computer_bigfix_id
- A field that identifies software: discoverable_guid that can be followed by the discovery_path parameter for precision
- bundle_name or bundle_guid or both
- Request
-
PUT api/sam/v2/software_instances?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623 { "rows": [ { "instance_id":4, "bundle_name":"Unified Governance \u0026 Integration" } ] }
- Response header
-
207 - OK
- Response body
-
{ "valid_instances": {"Assigned to CloudPak":1}, "invalid_instances":{}, "unmodified_instances":0 }
Assigning a component to a product and product to a Cloud Pak in one call
- instance_id or a combination of fields that includes:
- A field that identifies a computer: computer_dns_name or computer_bigfix_id
- A field that identifies software: discoverable_guid that can be followed by the discovery_path parameter for precision
- product_release_guid
- metric_id
- is_charged
- bundle_name or bundle_guid or both
- Request
-
PUT api/sam/v2/software_instances?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623 { "rows": [ { "instance_id":1423, "product_release_guid":"1bde5fc0-0e29-496a-b581-bacdaa75810f", "metric_id":5, "is_charged":1, "bundle_name":"IBM Db2 Standard Edition Extension for IBM Cloud Pak for Data" } ] }
- Response header
-
207 - OK
- Response body
-
{ "valid_instances": { "Bundled":1, "Assigned to CloudPak":1 }, "invalid_instances":{}, "unmodified_instances":0 }
Example conversation - migrating software assignments between BigFix servers
For more information, see: Tutorial: Migrating software assignments between two BigFix servers.