Classifying software (v2)

9.2.14 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.

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
Important: You can use this API to update or migrate software bundlings. However, you can only update the budlings that are defined in the software catalog. You cannot create custom bundlings through the API.

Resource information

Table 1. Resource information

The table consists of two columns and seven rows.

Operation details Description
HTTP method PUT
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 n/a element
Response format application/json
Response codes

207 – OK

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

Parameters

Important:
The following parameters are required to successfully complete the query:
  • 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.
Other parameters that are listed below are optional. You can include them in your query according to your needs. The out-of-range values for all the optional parameters are ignored.
Table 2. Parameters

The table consists of three columns and a few rows.

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
9.2.14 is_charged 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 User icon, and click Profile. Then, click Show token. 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
Note: You can change multiple values during a single request. For example, you can use a single request to reassign the component, and change its status to confirmed.

Example conversation

Request
PUT api/sam/v2/software_instances?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
200 - OK

Example conversation - migrating software assignments between BigFix servers

For more information, see: Tutorial: Migrating software assignments between two BigFix servers.