Tutorial: Migrating software assignments between two License Metric Tool servers
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.
- 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
-
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
withcomputer_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 } ... ] }
-
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 } ... ] }
-
Check the results of the test.
- Response header
-
Status code: 207
- Response body
Where:{ "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 } }
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 PakBundled
- instance in the new License Metric Tool will be reassigned to match the assignment from the old License Metric ToolConfirmed
- assignment of the instance in the new License Metric Tool will be confirmedExcluded
- instance in the new License Metric Tool will be excluded from license metric calculationsSuppressed
- instance in the new License Metric Tool will be suppressed from discoveryUnconfirmed
- instance in the new License Metric Tool is confirmed and will be unconfirmedUnsuppressed
- 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.
-
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.
-
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 } ... ] }
-
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.
- 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 (theoffset
parameter reaches or exceeds the number that was returned in thetotal
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.