Software Classification (v2)

Edit online

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.

Important:
  • 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.

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

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: 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 Required Value
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
verbose Descriptive information about the result of an API request. By default, this parameter is set to false.   Boolean
createCustomBundling By adding this parameter to API request the custom bundling relations will be created and used for all instances for which selected component are not listed as a bundling option in software catalog.   Boolean

Obtaining the required information

To obtain information that is needed to use the REST API, perform the following steps:
  1. 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.
  2. 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.
  3. 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://hostname: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://hostname: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://hostname: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://hostname: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 FlexPoint offering or a Cloud Pak

To assign a product to a FlexPoint offering or a Cloud Pak, 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://hostname: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://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,
         "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://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
}

Migrating software assignments

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