Setting license metric thresholds and custom field values (v2)

Available from 9.2.10. You use the PUT operation on the api/sam/v2/license_usage element to set up license metric thresholds as well as values of custom fields that were added on the All Metrics report.

Permissions

User You must have the Manage Contracts permission to use this API.

Resource URL

https://hostname:port/api/sam/v2/license_usage?token=token

Resource information

Table 1. Resource information

The table consists of two columns and seven rows.

Operation details Description
HTTP method PUT
Request headers
Header
Accept-Language (optional)
Values
en-US (only English is supported)

Negotiates the language of the response. If the header is not specified, the content is returned in the server language.

Request format application/json
Response headers
Header
Content-Type
Values
application/json

Specifies the content type of the response.

Header
Content-Language
Values
en-US, …

Specifies the language of the response content. If the header is not specified, the content is returned in the server language.

Header
computerGroupId
Values
Integer

Specifies ID of the computer group for which values are changed.

Response payload n/a
Response format application/json
Response codes

200 – OK

400 – "Bad Request" if a parameter contains errors

401 – "Unauthorized user" if the user whose token is used for authentication is not authorized to access the data

404 – "Not Found" if a parameter does not exist

406 – "Not Acceptable" if the import is in progress and the values cannot be updated. For information about checking the status of the import, see: Running data imports.

Schema description

To retrieve the list of all columns that are used by this REST API together with their descriptions, use the following request.
GET api/sam/v2/schemas/license_usage.json?token=token

Query parameters

Table 2. Query parameters

The table consists of three columns and 26 rows.

Column Description Required Type
computerGroupId Identifier of the computer group for which you want to update the values. If you do not specify this parameter, the values are updated for the computer group of the user whose token is used for authentication.

To view IDs of computer groups, log in to BigFix Inventory and go to Reports > Computer Groups. Then, hover of the Manage Report View icon Manage Report View icon, click Configure View, and select the ID column to display it on the report.

product_id Identifier of the software product. Integer
metric_id Identifier of the license metric. For the list of metric identifiers, see: Metric IDs and code names. String
threshold The maximum number of metric units that the product is entitled to use within a computer group. Integer
custom_field_number Custom field that was added to the All Metrics report. To view the list of all custom fields, view the license_usage.json schema. Various
Note: You can change multiple values during a single request. For example, you can use a single request to set the metric threshold, set a value of one custom field, and clear the value of another custom field.

Example conversation - setting a license metric threshold

  1. To retrieve information about the identifier of the product for which you want to set the license metric threshold, use the following GET request. The request returns product ID and name as well as metric ID and code name.
    Request
    GET api/sam/v2/license_usage?columns[]=product_id&columns[]=product_name
    &columns[]=metric_id&columns[]=metric_code_name&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
    Response
    [{
    "product_id": 29258,
    "product_name": "WebSphere Service Registry and Repository",
    "metric_id": 3,
    "metric_code_name": "PVU_FULL_CAP"
    }]
  2. To change the value of the license metric threshold, use the following PUT request.

    A relation between the product specified by the product_id parameter and the license metric specified by the metric_id parameter must exist in the software catalog. Otherwise, the request returns an error. If the relation does not exist in the software catalog, you can create it on the Products & Metrics panel. For more information, see: Assigning an additional metric to a product.

    Request
    PUT api/sam/v2/license_usage?product_id=29258&metric_id=3
    &threshold=300&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
    
    Response
    200 - OK
Tip: To automate the process, you can write a script that parses the results returned by the GET request, iterates through these results, and updates them one by one by using the PUT request.

Example conversation - setting the value of a custom field

  1. To check the list of custom fields that were created on the All Metrics report, view the license_usage.json schema. The schema lists all columns, including custom fields. Identify the custom field for which you want to set the value.
    Request - check the list of existing custom fields
    GET api/sam/v2/schemas/license_usage.json?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
    
    Response - list of all columns, including custom fields
    [{
    "product_name":
          {
           "type": "string",
           "description": "Name of the software product."
           },
    ...
    "custom_field_1":
           {
           "type": "boolean",
           "title": "Requires Extension"
           }
    }]
  2. After you identify the name of the custom field, use the following PUT request.
    Request
    PUT api/sam/v2/license_usage?product_id=29258&metric_id=3
    &custom_field_1=1&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
    
    Response
    200 - OK

Example conversation - clearing a license metric threshold

  1. To retrieve information about the identifier of the product for which you want to clear the license metric threshold, use the following GET request. The request returns product ID and name, metric ID and name, and the threshold value.
    Request
    GET api/sam/v2/license_usage?columns[]=product_id&columns[]=product_name
    &columns[]=metric_id&columns[]=metric_name&columns[]=threshold
    &token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
    Response
    [{
    "product_id": 29258,
    "product_name": "WebSphere Service Registry and Repository",
    "metric_id": 3,
    "metric_name": "PVU Full Capacity"
    "threshold": 300
    }]
  2. To clear the license metric threshold, specify an empty value in the threshold parameter. The same method is used for clearing values of custom fields.
    Request
    PUT api/sam/v2/license_usage?product_id=29258&metric_id=3
    &threshold=&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
    
    Response
    200 - OK