Software Classification (v2)

You can use this REST API to update, migrate, or create software assignments.
The number of software instances per single REST API request should not exceed 150.

Important: Software classification actions are not applied from the moment when they are performed. They affect the entire licensing history. For example, if a component is detected in January, and then it is reassigned to a different product or the product metric is changed in May, the change affects the component from January. The change is visible after you click Recalculate on the All Metrics report or after the next import of data completes.

Permissions

User You must have the View Endpoints and View Hardware Inventory permissions to use this API.

Resource URL

https://server_url:server_port/api/sam/v2/software_instances

Resource information

Table 1. Resource information
Operation details	Description
HTTP method	`PUT`
Request headers	`Accept-Language` (optional) Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language. Values: `en-US` (only English is supported) `Token` Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests. Values: an alphanumeric string that is generated in License Metric Tool
Request format	`application/json`
Response headers	`Content-Type` Use: Specifies the content type of the response. Values: `application/json` `Content-Language` Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language. Values: en-US, …
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

Request content

Every request must include information that identifies the software instance or instances. Information that identifies the instance can be the instance_id field, 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

Apart from that, a different set of fields is required depending on the operation that you want to perform. The fields are listed in example conversations:

Assigning a component to a product
Confirming software assignment
Excluding a product
Suppressing a component
Assigning a product to a Cloud Pak or other product 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

Apart from the fields that are required, you can also use other fields that are available when you use the GET operation on the api/sam/v2/software_instances REST API. For a complete list of fields, see: Table 2. Other fields are optional and you can include them in your query according to your needs. The out-of-range values for all optional fields are ignored.

You can use a single request to change multiple values. For example, to assign a component to a product and then the product to a Cloud Pak. The only exception is when you include a product in the pricing calculation or unsuppress a component. By design, these actions make the software assignment unconfirmed. Use the same REST API call again to confirm such software assignments. You can confirm the reassignment of a component to a different product, exclusion of a product or suppression of a component. However, since confirmation is performed in scope of the main action, it is not counted towards confirmed instances in the response summary containing the list of the changes applied.

Parameters

Table 2. Parameters
Parameter	Description	Value
computer_group_id	When you add this parameter to the request, you can perform the action within the scope of your additional computer group. If you do not specify this parameter, the action is completed for the main computer group to which you have access. To obtain the value of the computer_group_id parameter, perform the following steps. In License Metric Tool, hover over Reports, and click Computer Groups. To add the ID column to the report view, hover over Configure, and click Configure View. Select the ID column, and click Submit.	Integer
createCustomBundling	When you add this parameter to the request, custom bundling relations are created and used for all instances for which the selected component is not listed as a bundling option in the software catalog.	Boolean
simulate	When you add this parameter to the request, you can test the request to view its results and status. By default, this parameter is set to false.	Boolean
verbose	Descriptive information about the results of an API request. By default, this parameter is set to false.	Boolean

Obtaining the required information

To obtain information that is needed to use the REST API, perform the following steps:

Use the user interface to perform the action that you want to automate with REST API on a single instance. For example, assign a component to a product.
Use the GET operation on the api/sam/v2/software_instances to obtain information such as instance_id of the affected software instance and the instances that you want to modify, product_release_guid, metric_id, and other depending on the action that you want to complete.
Use the PUT operation on the api/sam/v2/software_instances to change the remaining software instances in the same way.

Assigning a component to a product

To assign a component to a product, 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

Request

PUT https://server_url:server_port/api/sam/v2/software_instances

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

Request body

{
    "rows": [
      {
         "instance_id":2,
         "metric_id":-15896,
         "product_release_guid":"517a3a05-d37a-4db9-a01a-add7ab11b716",
         "is_charged":1
       }
    ]
}

Response header

207 - OK

Response body

{
"valid_instances":
       {"Bundled":1},
"invalid_instances":{},
"unmodified_instances":0
}

Confirming software assignment

To confirm a component, 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
is_confirmed

Request

PUT https://server_url:server_port/api/sam/v2/software_instances

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

Request body

{
    "rows": [
      {
         "instance_id":245,
         "is_confirmed":1
       }
      {
         "instance_id":246,
         "is_confirmed":1
       }
    ]
}

Response header

207 - OK

Response body

{
"valid_instances":
     {"Confirmed":2},
"invalid_instances":{},
"unmodified_instances":0
}

Excluding a product

To exclude a product, 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
is_excluded

Request

PUT https://server_url:server_port/api/sam/v2/software_instances

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

Request body

{
    "rows": [
      {
         "computer_dns_name":"<name>",
         "discoverable_guid":"861f7ad0-58fe-4718-ba03-906934057651"
         "is_excluded":1
       }
    ]
}

Response header

207 - OK

Response body

{
"valid_instances":
       {"Excluded":1},
"invalid_instances":{},
"unmodified_instances":0
}

Suppressing a component

To suppress a component, 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
is_suppressed

Request

PUT https://server_url:server_port/api/sam/v2/software_instances

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

Request body

{
    "rows": [ 
      {
         "instance_id":2,
         "is_suppressed":1
       }
    ]
}

Response header

207 - OK

Response body

{
"valid_instances":
       {"Suppressed":1},
"invalid_instances":{},
"unmodified_instances":0
}

Assigning a product to a Cloud Pak or other product bundle

To assign a product to a Cloud Pak, or other product bundle such as a FlexPoint, 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 https://server_url:server_port/api/sam/v2/software_instances

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

Request body

{
    "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 https://server_url:server_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,
         "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.
(Optionally if bundling to Cloud Pak needs to be done in the same request) bundle_name or bundle_guid or both.

Example 1

Request

PUT https://server_url:server_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://server_url:server_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
}

Migrating software assignments

For more information, see: Tutorial: Migrating software assignments between two License Metric Tool servers.