Classifying software (v2)

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 Cloud Pak or FlexPoint Bundle
Assigning a component to a product and product to a Cloud Pak in one call
Assigning components to products and Cloud Paks according to custom bundling relations

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.
Response headers	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
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 , 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

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

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.