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.

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

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. You can only update the budlings that are defined in the software catalog or were earlier created manually in WebUI.

Resource information

Table 1. Resource information
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 assign a component instance to a product requests:
  • 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.
Requests, such as suppression and exclusion require different set of parameters as described in the table below.
Table 2. ParametersParameters 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.
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

  1. 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 
    } 
  2. 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 
    } 
  3. 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 
    } 
  4. 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 
    } 
  5. 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 
    } 

Example conversation - migrating software assignments between BigFix servers

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