Setting license metric thresholds and custom field values (v2)

Edit online

9.2.10 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 Thresholds and Metric Custom Fields (previously: Manage Contracts) permission to use this API.

Resource URL

https://hostname:port/api/sam/v2/license_usage

Resource information

Table 1. Resource information
Operation details	Description
HTTP method	`PUT`
Request headers	`Accept-Language` (optional) Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language. Values: `en-US` (only English is supported) `Token` Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests. Values: an alphanumeric string that is generated in License Metric Tool
Request format	`application/json`
Response headers	`Content-Type` Use: Specifies the content type of the response. Values: `application/json` `Content-Language` Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language. Values: en-US, … `computerGroupId` Use: Specifies ID of the computer group for which values are changed. Values: Integer
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: REST API for 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 https://hostname:port/api/sam/v2/schemas/license_usage.json

Query parameters

Table 2. Query parameters
Column	Description	Required	Type
bundle_id	Identifier of the FlexPoint bundle or Cloud Pak to which the product is assigned.	✓	String
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 License Metric Tool and go to Reports > Computer Groups. Then, hover over Configure, click Configure View, and select the ID column to display it on the report.
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
metric_id	Identifier of the license metric. For the list of metric identifiers, see: Metric IDs and code names.	✓	String
product_id	Identifier of the software product.	✓	Integer
threshold	The maximum number of metric units that the product is entitled to use within a computer group.		Integer

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 https://hostname:port/api/sam/v2/license_usage?columns[]=product_id&columns[]=product_name
&columns[]=metric_id&columns[]=metric_code_name

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

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.
Request
```
PUT https://hostname:port/api/sam/v2/license_usage
?product_id=29258&metric_id=3&threshold=300&bundle_id=0
```
Request header
```
Accept: application/json 
Accept-Language: en-US
Token: <token>
```
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 https://hostname:port/api/sam/v2/schemas/license_usage.json
```
Request header
```
Accept: application/json 
Accept-Language: en-US
Token: <token>
```
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 https://hostname:port/api/sam/v2/license_usage
?product_id=29258&metric_id=3&bundle_id=0&custom_field_1=1

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

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 https://hostname:port/api/sam/v2/license_usage?columns[]=product_id
&columns[]=product_name&columns[]=metric_id&columns[]=metric_name&columns[]=threshold

Request header

Accept: application/json 
Accept-Language: en-US
Token: <token>

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 https://hostname:port/api/sam/v2/license_usage
?product_id=29258&metric_id=3&threshold=&bundle_id=0
```
Request header
```
Accept: application/json 
Accept-Language: en-US
Token: <token>
```
Response
```
200 - OK
```