Tutorial: Migrating software assignments between two License Metric Tool servers

Edit online

9.2.14 Available from 9.2.14.
This tutorial teaches you how to use REST API requests to migrate software assignments when the License Metric Tool server is migrated between two operating systems.

Before you begin

  • Software and capacity scans must be scheduled and software must be discovered in the new instance of License Metric Tool.
  • User You must have the View Endpoints and View Hardware Inventory permissions to perform this task.
  • If some of the assignments are using custom bundling options defined in the old License Metric Tool, use the createCustomBundling parameter in the REST API PUT requests as in below examples to automatically create the same custom bundling options in the new License Metric Tool. For more information, see: Software Classification (v2).
  • It might happen that not all software instances are properly migrated for various reasons. Address such instances directly in the new License Metric Tool.

About this task

For best results, migrate software assignments in batches. The number of software instances per single REST API request should not exceed 150.

Procedure

  1. To retrieve information about the first 150 software assignments, use the following GET request against the old License Metric Tool. The limit parameter defines the number of instances for which you retrieve information.
    Request
    GET https://hostname:port/api/sam/v2/software_instances?limit=150&
columns[]=product_name&columns[]=component_name&columns[]=discovery_path&columns[]=is_charged&
columns[]=is_confirmed&columns[]=computer_bigfix_id&columns[]=discoverable_guid&columns[]=product_release_guid&
columns[]=metric_id&columns[]=bundle_guid&criteria={"and":[["is_present","=","1"]]}
    • For information about the meaning of each retrieved column, see: Retrieval of software inventory (v2).
    • If you use a disconnected data source, not BigFix®, substitute the computer_bigfix_id with computer_dns_name in the request.
    Request header
    Accept: application/json 
Accept-Language: en-US
Token: <token>
    For information how to obtain the token, see: Authenticating REST API requests.
    Response body
    The total parameter indicates how many software instances exist in the old License Metric Tool. 
    {
  "total": 23222,
  "rows": [{
    "product_name": "IBM Algo One Counterparty Credit Risk CVA Add-on",
    "component_name": "IBM Algo One Counterparty Credit Risk CVA Add-on",
    "discovery_path": ["/root/fbartman/tags/TAGS/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1088643518,
    "discoverable_guid": "bd3da08f-d33f-4f8e-8a44-91150fbcbd61",
    "product_release_guid": "a7fe41cf-f25f-452b-ae31-113d62579483",
    "metric_id": -15896,
    "bundle_guid": 0
  }, {
    "product_name": "IBM InfoSphere Global Name Management Non-Production Environment",
    "component_name": "IBM InfoSphere Global Name Management for Non-Production Environments",
    "discovery_path": ["/opt/readiness/tags/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1625524069,
    "discoverable_guid": "138a900a-27cc-4225-81cb-12d2ac99151e",
    "product_release_guid": "517a3a05-d37a-4db9-a01a-add7ab11b716",
    "metric_id": -15896,
    "bundle_guid": 0
  }, {
    "product_name": "IBM InfoSphere Global Name Management Non-Production Environment",
    "component_name": "IBM InfoSphere Global Name Management for Non-Production Environments",
    "discovery_path": ["/root/fbartman/tags/TAGS/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1088643518,
    "discoverable_guid": "138a900a-27cc-4225-81cb-12d2ac99151e",
    "product_release_guid": "517a3a05-d37a-4db9-a01a-add7ab11b716",
    "metric_id": -15896,
    "bundle_guid": 0
  }
 ...
  ]
}
  2. To simulate the migration, use the following PUT request against the new License Metric Tool. Use the Body of the response that you obtained in step 1. The simulation allows you to see how many instances will be affected in what way without modifying the new License Metric Tool.
    Request
    PUT https://hostname:port/api/sam/v2/software_instances?createCustomBundling=true&simulate=true&verbose=true
    Request header
    Accept: application/json 
Accept-Language: en-US
Token: <token>
    Request body
    {
  "total": 23222,
  "rows": [{
    "product_name": "IBM Algo One Counterparty Credit Risk CVA Add-on",
    "component_name": "IBM Algo One Counterparty Credit Risk CVA Add-on",
    "discovery_path": ["/root/fbartman/tags/TAGS/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1088643518,
    "discoverable_guid": "bd3da08f-d33f-4f8e-8a44-91150fbcbd61",
    "product_release_guid": "a7fe41cf-f25f-452b-ae31-113d62579483",
    "metric_id": -15896,
    "bundle_guid": 0
  }, {
    "product_name": "IBM InfoSphere Global Name Management Non-Production Environment",
    "component_name": "IBM InfoSphere Global Name Management for Non-Production Environments",
    "discovery_path": ["/opt/readiness/tags/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1625524069,
    "discoverable_guid": "138a900a-27cc-4225-81cb-12d2ac99151e",
    "product_release_guid": "517a3a05-d37a-4db9-a01a-add7ab11b716",
    "metric_id": -15896,
    "bundle_guid": 0
  }, {
    "product_name": "IBM InfoSphere Global Name Management Non-Production Environment",
    "component_name": "IBM InfoSphere Global Name Management for Non-Production Environments",
    "discovery_path": ["/root/fbartman/tags/TAGS/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1088643518,
    "discoverable_guid": "138a900a-27cc-4225-81cb-12d2ac99151e",
    "product_release_guid": "517a3a05-d37a-4db9-a01a-add7ab11b716",
    "metric_id": -15896,
    "bundle_guid": 0
  }
 ...
  ]
}
  3. Check the results of the test.
    Response header
    Status code: 207
    Response body
    {
  "details": {
    "valid_instances": {
      "Bundled":{
        "1": "instance_ids: 1,5,6,7,16,..." 
      "Confirmed": {
        "1": "instance_ids: 112,113,114,..."
      }
    },
    "invalid_instances": {},
    "unmodified_instances": {
      "2": "instance_ids: 2",
      "3": "instance_ids: 3",
      "4": "instance_ids: 4",
      "8": "instance_ids: 8",
      ...
    }
  },
  "summary": {
    "valid_instances": {
      "Bundled": 75
      "Confirmed": 60
    },
    "invalid_instances": 5,
    "unmodified_instances": 10
  }
}
    Where:
    valid_instances
    Instances that exist in the new License Metric Tool and will be modified to match the assignments from the old License Metric Tool. These instances can fall into one of the following categories.
    • Assigned to CloudPak - instance in the new License Metric Tool will be assigned to a Cloud Pak
    • Bundled - instance in the new License Metric Tool will be reassigned to match the assignment from the old License Metric Tool
    • Confirmed - assignment of the instance in the new License Metric Tool will be confirmed
    • Excluded - instance in the new License Metric Tool will be excluded from license metric calculations
    • Suppressed - instance in the new License Metric Tool will be suppressed from discovery
    • Unconfirmed - instance in the new License Metric Tool is confirmed and will be unconfirmed
    • Unsuppressed - instance in the new License Metric Tool is suppressed and will be unsuppressed
    invalid_instances
    Instances that will not be modified in the new License Metric Tool because they are not valid. Identify such instances and address them directly in the new License Metric Tool. For example, by assigning them on the Software Classification report.
    unmodified_instances
    Instances that exist in the new License Metric Tool, but already match the assignments from the old License Metric Tool and thus will not be modified.
  4. Use the following PUT request against the new License Metric Tool to migrate the software assignments. Results of the REST API request include a summary of changes that were made.
    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
    {
  "total": 23222,
  "rows": [{
    "product_name": "IBM Algo One Counterparty Credit Risk CVA Add-on",
    "component_name": "IBM Algo One Counterparty Credit Risk CVA Add-on",
    "discovery_path": ["/root/fbartman/tags/TAGS/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1088643518,
    "discoverable_guid": "bd3da08f-d33f-4f8e-8a44-91150fbcbd61",
    "product_release_guid": "a7fe41cf-f25f-452b-ae31-113d62579483",
    "metric_id": -15896,
    "bundle_guid": 0
  }, {
    "product_name": "IBM InfoSphere Global Name Management Non-Production Environment",
    "component_name": "IBM InfoSphere Global Name Management for Non-Production Environments",
    "discovery_path": ["/opt/readiness/tags/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1625524069,
    "discoverable_guid": "138a900a-27cc-4225-81cb-12d2ac99151e",
    "product_release_guid": "517a3a05-d37a-4db9-a01a-add7ab11b716",
    "metric_id": -15896,
    "bundle_guid": 0
  }, {
    "product_name": "IBM InfoSphere Global Name Management Non-Production Environment",
    "component_name": "IBM InfoSphere Global Name Management for Non-Production Environments",
    "discovery_path": ["/root/fbartman/tags/TAGS/isoTagsRepo"],
    "is_charged": 1,
    "is_confirmed": 0,
    "computer_bigfix_id": 1088643518,
    "discoverable_guid": "138a900a-27cc-4225-81cb-12d2ac99151e",
    "product_release_guid": "517a3a05-d37a-4db9-a01a-add7ab11b716",
    "metric_id": -15896,
    "bundle_guid": 0
  }
 ...
  ]
}
    Response body
    {
  "valid_instances": {
        "Bundled": 149
  },
  "invalid_instances": {},
  "unmodified_instances": 1
}
    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.
  5. To retrieve information about the second batch of software assignments, use the following GET request against the old License Metric Tool. The offset parameter indicates how many rows to skip in the request because they were already retrieved in the previous request.
    Request
    GET https://hostname:port/api/sam/v2/software_instances?limit=150&
offset=150&columns[]=product_name&columns[]=component_name&columns[]=discovery_path&columns[]=is_charged&
columns[]=is_confirmed&columns[]=computer_bigfix_id&columns[]=discoverable_guid&columns[]=product_release_guid&
columns[]=metric_id&columns[]=bundle_guid&criteria={"and":[["is_present","=","1"]]}
    Request header
    Accept: application/json 
Accept-Language: en-US
Token: <token>
    Response body
    {
"total": 23222,
"rows":[
   {
      "product_name":"IBM Emptoris Sourcing",
      "component_name":"IBM Emptoris Sourcing",
      "discovery_path":["/opt/readiness/tags/isoTagsRepo"],
      "is_charged":1,
      "is_confirmed":0,
      "computer_bigfix_id":1625524069,
      "discoverable_guid":"c22efb5c-8f5a-4dfc-ae16-ffa410de84cd",
      "product_release_guid":"e53bd188-b3c5-48ef-b718-3f0567a694c2",
      "metric_id":3774
      "bundle_guid":0
   },
   {
      "product_name":"IBM Emptoris Sourcing",
      "component_name":"IBM Emptoris Sourcing",
      "discovery_path":["/usr/citagent/data/wscansw_signatures/5k_dir_8k_files/unix/b/d/3/Linux_all/isoTagsRepo"],
      "is_charged":1,
      "is_confirmed":0,
      "computer_bigfix_id":1612654062,
      "discoverable_guid":"c22efb5c-8f5a-4dfc-ae16-ffa410de84cd",
      "product_release_guid":"e53bd188-b3c5-48ef-b718-3f0567a694c2",
      "metric_id":3774
      "bundle_guid":0
   },
   {
      "product_name":"IBM Emptoris Sourcing",
      "component_name":"IBM Emptoris Sourcing",
      "discovery_path":["/root/fbartman/tags/TAGS/isoTagsRepo"],
      "is_charged":1,
      "is_confirmed":0,
      "computer_bigfix_id":1088643518,
      "discoverable_guid":"c22efb5c-8f5a-4dfc-ae16-ffa410de84cd",
      "product_release_guid":"e53bd188-b3c5-48ef-b718-3f0567a694c2",
      "metric_id":3774}
      "bundle_guid":0
   }
   ...
   ]
}
  6. Use the following PUT request against the new License Metric Tool to migrate the software assignments.
    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
    {
"total": 23222,
"rows":[
   {
      "product_name":"IBM Emptoris Sourcing",
      "component_name":"IBM Emptoris Sourcing",
      "discovery_path":["/opt/readiness/tags/isoTagsRepo"],
      "is_charged":1,
      "is_confirmed":0,
      "computer_bigfix_id":1625524069,
      "discoverable_guid":"c22efb5c-8f5a-4dfc-ae16-ffa410de84cd",
      "product_release_guid":"e53bd188-b3c5-48ef-b718-3f0567a694c2",
      "metric_id":3774
   },
   {
      "product_name":"IBM Emptoris Sourcing",
      "component_name":"IBM Emptoris Sourcing",
      "discovery_path":["/usr/citagent/data/wscansw_signatures/5k_dir_8k_files/unix/b/d/3/Linux_all/isoTagsRepo"],
      "is_charged":1,
      "is_confirmed":0,
      "computer_bigfix_id":1612654062,
      "discoverable_guid":"c22efb5c-8f5a-4dfc-ae16-ffa410de84cd",
      "product_release_guid":"e53bd188-b3c5-48ef-b718-3f0567a694c2",
      "metric_id":3774
   },
   {
      "product_name":"IBM Emptoris Sourcing",
      "component_name":"IBM Emptoris Sourcing",
      "discovery_path":["/root/fbartman/tags/TAGS/isoTagsRepo"],
      "is_charged":1,
      "is_confirmed":0,
      "computer_bigfix_id":1088643518,
      "discoverable_guid":"c22efb5c-8f5a-4dfc-ae16-ffa410de84cd",
      "product_release_guid":"e53bd188-b3c5-48ef-b718-3f0567a694c2",
      "metric_id":3774,
   }
   ...
   ]
}
    Response body
    {
  "valid_instances": {
        "Bundled": 149
  },
  "invalid_instances": {},
  "unmodified_instances": 1
}
    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.
  7. Repeat steps 5 and 6 for the subsequent batches of software assignments by changing the offset parameter. Increment the parameter by 150 until you migrate all instances (the offset parameter reaches or exceeds the number that was returned in the total parameter). A single request can change multiple values. For example, 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. Issue twice the REST API calls in steps 4 and 6 to make sure the software assignment is correctly confirmed.