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 , 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

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 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

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
```