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
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
Operation details | Description |
---|---|
HTTP method | PUT |
Request headers |
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 |
Specifies the content type of the response. |
Specifies the language of the response content. If the header is not specified, the content is returned in the server language. |
|
Specifies ID of the computer group for which values are changed. |
|
Response payload | n/a |
Response format | application/json |
Response codes |
|
Schema description
GET api/sam/v2/schemas/license_usage.json?token=token
Query parameters
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 . Then, hover of the 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 |
Example conversation - setting a license metric threshold
- 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" }]
- 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 themetric_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
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
- 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" } }]
- 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
- 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 }]
- 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