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

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

10.0.8Assigning a product to a Cloud Pak or FlexPoint Bundle

To assign a product to a Cloud Pak or FlexPoint Bundle, the following fields are required:
  • 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
}

10.0.8 Assigning a component to a product and product to a Cloud Pak in one call

To assign a component to a product and then the product to a Cloud Pak in one REST API call, the following fields are required:
  • 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
}

Assigning components to products and Cloud Paks according to custom bundling relations

To assign a component to a product and potentially next the product to a Cloud Pak using custom bundling relation, the following fields are needed:

  • 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
  • create_custom_bundling set to 1 or createCustomBundling set globally for entire HTTP PUT request.
  • bundle_name or bundle_guid or both, if bundling to Cloud Pak needs to be done in the same request

Example 1
Request
PUT https://hostname:port/api/sam/v2/software_instances
Request header
Accept: application/json 
             Accept-Language: en-US
             Token: <token>
Request body
{
    "rows": [
        {
             "instance_id":1423,
             "product_release_guid":"1bde5fc0-0e29-496a-b581-bacdaa75810f",
             "metric_id":5,
             "is_charged":1,
             "create_custom_bundling":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 2

Request
PUT https://hostname:port/api/sam/v2/software_instances?createCustomBundling=true
Request header
Accept: application/json 
             Accept-Language: en-US
             Token: <token>
Request body
{
    "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
}

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