Tutorial: Software classification using REST API

Edit online

This tutorial teaches you how to reassign software instance to different product, confirm software instance assignment to product, exclude software instance from pricing calculations and suppress software instance using the REST API and a cURL command line tool.

Before you begin

You must have root operating system privileges.

About this task

After software scan data is imported from the BigFix® server, software instances are automatically associated with products based on automatic bundling rules. If some instances are assigned to the wrong product, they must be reassigned correctly.

In this tutorial, you retrieve the software instances discovered on computer computer_1. Then you check the possible bundling options for the FlashCopy® component and reassign it to the IBM MQ Advanced product under IBM Cloud Pak for Integration Cloud Pak as well as you confirm IBM License Metric Tool - Server component assignment to IBM License Metric Tool product, exclude IBM Db2 Standard Edition VPC Option product from pricing calculation and suppress IBM License Metric Tool component.

Important:
  • Some of the commands in this tutorial are long, and for the purposes of presentation, some line breaks were introduced. Treat each line break as a no character.
  • You must include License Metric Tool user API token in a header of each cURL command. For more information, see: Retrieval of software inventory (v2).

Procedure

  1. Log on to your computer and start the command line interface.
  2. Retrieve a list of all software instances that are discovered on computer computer_1. Run the following command: 
    curl -X GET -v -g -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Token: token' -i 'https://server_url:server_port/api/sam/v2/software_instances?columns[]=instance_id&columns[]=discoverable_guid&columns[]=component_name&columns[]=product_name&columns[]=metric_code_name&columns[]=is_charged&columns[]=is_confirmed&columns[]=is_excluded&columns[]=is_suppressed&columns[]=exclusion_or_suppress_comment&columns[]=bundle_guid&criteria={"and":[["computer_name","=","computer_1"]]}'
  3. Review the list to obtain the GUID of the IBM MQ component. 
    {
   "total":4,
   "rows":[
      {
         "instance_id":47,
         "discoverable_guid":"3B2F6B0D-1489-4395-AB5A-801EE678315A",
         "component_name":"IBM License Metric Tool",
         "product_name":"IBM License Metric Tool",
         "metric_code_name":"ESTABLISHMENT",
         "is_charged":0,
         "is_confirmed":0,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      },
      {
         "instance_id":48,
         "discoverable_guid":"9EA55381-E070-4223-AAAC-14A554E097DB",
         "component_name":"IBM License Metric Tool - Server",
         "product_name":"IBM License Metric Tool",
         "metric_code_name":"ESTABLISHMENT",
         "is_charged":0,
         "is_confirmed":0,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      },
      {
         "instance_id":53,
         "discoverable_guid":"B3637504-5E9C-4889-9A9A-51835C882CCD",
         "component_name":"IBM Db2 Standard Edition VPC Option",
         "product_name":"IBM Db2 Standard Edition VPC Option",
         "metric_code_name":"VIRTUAL_PROCESSOR_CORE",
         "is_charged":1,
         "is_confirmed":0,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      },
      {
         "instance_id":54,
         "discoverable_guid":"B1BAC35F-7486-44E3-A44E-4FE143CB4034",
         "component_name":"IBM MQ",
         "product_name":"IBM MQ",
         "metric_code_name":"INTERNAL_PVU",
         "is_charged":0,
         "is_confirmed":0,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      }
   ]
}
  4. Retrieve a list of the products to which the IBM MQ component can be reassigned to. Use a discoverable GUID you obtained in the previous step. Run the following command: 
    curl -g -X GET -k -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Token: token' -i 'https://server_url:server_port/api/sam/v2/bundling_options?criteria={"and":[["discoverable_guid","=","B1BAC35F-7486-44E3-A44E-4FE143CB4034"]]}'
  5. Review the list to obtain the IBM® product release GUID, metric ID and Cloud Pak bundle GUID you want to reassign the instance to. Also, verify whether the assignment should be charged or not. 
    {
   "total":6766,
   "rows":[
(...)
      {
         "component_name":"IBM MQ",
         "component_release":"9.0",
         "discoverable_guid":"B1BAC35F-7486-44E3-A44E-4FE143CB4034",
         "product_name":"IBM MQ Advanced",
         "product_release":"9.0",
         "product_release_guid":"A205E872-0EB5-4BE9-8F55-02DB73A6C27E",
         "metric_id":5844,
         "metric_code_name":"VIRTUAL_PROCESSOR_CORE",
         "bundle_name":"IBM Cloud Pak for Integration",
         "bundle_guid":"C8B82D18-9E75-45F0-892D-B9EF2731B90D",
         "is_charged":1,
         "is_custom":0
      },
(...)
   ]
}
  6. Reassign the IBM MQ component to the IBM MQ Advanced product under IBM Cloud Pak for Integration Cloud Pak as well as confirm IBM License Metric Tool - Server component assignment to IBM License Metric Tool product, exclude IBM Db2 Standard Edition VPC Option product from pricing calculation and suppress IBM License Metric Tool component. You reflect this by changing the list obtained in the step 3 in the following way. 
    {
   "total":4,
   "rows":[
      {
         "instance_id":47,
         "discoverable_guid":"3B2F6B0D-1489-4395-AB5A-801EE678315A",
         "component_name":"IBM License Metric Tool",
         "product_name":"IBM License Metric Tool",
         "metric_code_name":"ESTABLISHMENT",
         "is_charged":0,
         "is_confirmed":0,
         "is_excluded":0,
         "is_suppressed":1,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      },
      {
         "instance_id":48,
         "discoverable_guid":"9EA55381-E070-4223-AAAC-14A554E097DB",
         "component_name":"IBM License Metric Tool - Server",
         "product_name":"IBM License Metric Tool",
         "metric_code_name":"ESTABLISHMENT",
         "is_charged":0,
         "is_confirmed":1,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      },
      {
         "instance_id":53,
         "discoverable_guid":"B3637504-5E9C-4889-9A9A-51835C882CCD",
         "component_name":"IBM Db2 Standard Edition VPC Option",
         "product_name":"IBM Db2 Standard Edition VPC Option",
         "metric_code_name":"VIRTUAL_PROCESSOR_CORE",
         "is_charged":1,
         "is_confirmed":0,
         "is_excluded":1,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      },
      {
         "instance_id":54,
         "discoverable_guid":"B1BAC35F-7486-44E3-A44E-4FE143CB4034",
         "component_name":"IBM MQ",
         "product_release_guid":"A205E872-0EB5-4BE9-8F55-02DB73A6C27E",
         "metric_id":5844,
         "is_charged":1,
         "is_confirmed":0,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":"C8B82D18-9E75-45F0-892D-B9EF2731B90D"
      }
   ]
}
  7. Run the following command: 
    curl -g -X PUT -k -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Token: token' -i 'https://server_url:server_port/api/sam/v2/software_instances' --data '{"total":4,"rows":[{"instance_id":47,"is_suppressed":1},{"instance_id":48,"is_confirmed":1},{"instance_id":53,"is_excluded":1},{"instance_id":54,"metric_id":5844,"product_release_guid":"A205E872-0EB5-4BE9-8F55-02DB73A6C27E","is_charged":1,"is_confirmed":1,"bundle_guid":"C8B82D18-9E75-45F0-892D-B9EF2731B90D"}]}'
    An HTTP response 207 is received. The software instances are updated accordingly. The following output is returned:
    {
   "valid_instances":{
      "Bundled":1,
      "Assigned to CloudPak":1,
      "Suppressed":1,
      "Excluded":1,
      "Confirmed":1
   },
   "invalid_instances":{},
   "unmodified_instances":0
}
    Note: The reassignment of a component to a different product, exclusion of a product or suppression of a component is also confirmed if it was confirmed in the old License Metric Tool. 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.
  8. If you execute the same command as in step 2 once again, you get the following output confirming the changes were applied. 
    {
   "total":4,
   "rows":[
      {
         "instance_id":47,
         "discoverable_guid":"3B2F6B0D-1489-4395-AB5A-801EE678315A",
         "component_name":"IBM License Metric Tool",
         "product_name":null,
         "metric_code_name":null,
         "is_charged":null,
         "is_confirmed":0,
         "is_excluded":null,
         "is_suppressed":1,
         "exclusion_or_suppress_comment":"",
         "bundle_guid":null
      },
      {
         "instance_id":48,
         "discoverable_guid":"9EA55381-E070-4223-AAAC-14A554E097DB",
         "component_name":"IBM License Metric Tool - Server",
         "product_name":"IBM License Metric Tool",
         "metric_code_name":"ESTABLISHMENT",
         "is_charged":0,
         "is_confirmed":1,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":null
      },
      {
         "instance_id":53,
         "discoverable_guid":"B3637504-5E9C-4889-9A9A-51835C882CCD",
         "component_name":"IBM Db2 Standard Edition VPC Option",
         "product_name":"IBM Db2 Standard Edition VPC Option",
         "metric_code_name":"VIRTUAL_PROCESSOR_CORE",
         "is_charged":1,
         "is_confirmed":0,
         "is_excluded":1,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":"",
         "bundle_guid":null
      },
      {
         "instance_id":54,
         "discoverable_guid":"B1BAC35F-7486-44E3-A44E-4FE143CB4034",
         "component_name":"IBM MQ",
         "product_name":"IBM MQ Advanced",
         "metric_code_name":"VIRTUAL_PROCESSOR_CORE",
         "is_charged":1,
         "is_confirmed":0,
         "is_excluded":0,
         "is_suppressed":0,
         "exclusion_or_suppress_comment":null,
         "bundle_guid":"C8B82D18-9E75-45F0-892D-B9EF2731B90D"
      }
   ]
}