The Usage Per User endpoint delivers license usage metrics specific to the Usage Per User report for selected types of aggregation (username, hostname, username and hostname, usergroup, hostgroup), over a given timeframe.
Obtaining information about usage per user for a feature
You can easily fetch metrics about usage per user for a single feature by sending the following HTTP request.
GET /api/v1/report/feature/${featureId}/usage-per-user/${returnType}?sd=${startDate}&ed=${endDate}&grat=${granularity}$(additional parameters, as needed)
where $ indicates a variable value that you can replace with a value that best suits your needs. The possible parameters are described below.
Parameter | Required | Type | Description |
---|---|---|---|
${featureId} | Yes | integer | Specifies feature-specific parameters. |
${returnType} | Yes | string | Specifies the format in which license usage data will be returned. The format can be one of the following: json, csv, xls, xlsx, pdf. |
sd | Yes | string | Specifies the start date for which the report will be generated. The date is in YYYY-MM-DD format; for example, 2017-05-20. |
ed | Yes | string | Specifies the end date for which the report will be generated. The date is in YYYY-MM-DD format; for example, 2017-05-27. |
grat | Yes | integer | Specifies granularity of the returned data, which can be one of the following:
|
agrt | No | integer | Specifies type of aggregation of the returned data. Aggregation type can be one of the following:
By default, data is aggregated by username and hostname. |
rn | No | string | Specifies the name of the report that will be displayed once the report has been exported to PDF or XLS/XLSX. For CSV and JSON formats this parameter will be ignored. Note: If you don't pass this parameter, it will be generated automatically for PDF and XLS/XLSX types. If provided, it cannot be left empty. |
filter | No | json/string | Applies filtering license usage data on all fields. To filter by a string column, use the following format. [ { "type": "string", "field": ""${fud | un | ugn | hn | hgn | lsn | fns | fv | ftype}", "value": "${value}" } ] To filter by a numeric column, use the following format. [ { "type": "numeric", "comparison": "${gt | lt | eq}", "field": "${musage | hu | mu | hb | mb}", "value": "${value}" } ] |
fieldsVisibility | No | json/string | Specifies field visibility settings, like this: { "fud": "1", "un": "1", "ugn": "1", "hn": "1", "hgn": "1", "lsn": "1", "fns": "1", "fv": "1", "ftype": "1", "musage": "1", "hu": "1", "mu": "1", "hb": "1", "mb": "1" } where "1" indicates that a specific field is visible and ''0" indicates that it is not. Note that the order of the settings you make is important – when exported, the fields will be visible in exactly the same order you specify here. |
limit | No | integer | Determines the maximum number of data records that can be returned. The value must be greater than zero. |
offset | No | integer | Specifies the offset of the first row to return. |
orderBy | No | string | Specifies the field by which you want to order your data records. The field name can be one of the following: fud | un | ugn | hn | hgn | lsn | fns | fv | ftype | musage | hu | mu | hb | mb (See this section for more field-specific information.) If orderBy is provided, orderDirection is mandatory. |
orderDirection | No | string | Determines whether the sorting results will be displayed in ascending (ASC) or descending (DESC) order. If orderDirection is provided, orderBy is mandatory. |
Response
The following code block shows an example result of a successful request.
{ "success": ${success}, "msg": ${message}, "data": [ { "fid": ${featureId}, "lsid": ${licenseServerId}, "uid": ${userId}, "uil": ${userIsLdap}, "fud": ${date}, "un": ${username}, "ugn": ${userGroupName}, "hn": ${hostname}, "hgn": ${hostGroupName}, "lsn": ${licenseServerName}, "fns": ${featureName}, "fv": ${featureVersion}, "ftype": ${featureType}, "musage": ${maxUsage}, "hu": ${hoursUsed}, "mu": ${maxUsed}, "hb": ${hoursBorrowed}, "mb": ${maxBorrowed} } ], "code": ${code}, "totalCount": ${count} }
where the response fields can be explained as follows.
Field | Type | Description |
---|---|---|
success | boolean | Indicates whether your API request was successfully processed. |
msg | string | Error message returned on failure. |
fid | integer | Feature ID. |
lsid | integer | License server ID. |
uid | integer | User ID. |
uil | boolean | Information about whether the user is managed by LDAP. |
fud | string | Indicates period of time for which usage information is generated, i.e. date and time for hourly usage and dates for the remaining granularity options. |
un | string | Username or semicolon-separated list of usernames, depending on the aggregation type. |
ugn | string | Name of user group. This field is returned only when the requested aggregation type was usergroup. |
hn | string | Hostname or semicolon-separated list of hostnames, depending on aggregation type. |
hgn | string | Name of host group. This field is returned only when requested aggregation type was hostgroup. |
lsn | string | License server name. |
fns | string | Feature name. |
fv | string | Feature version. |
ftype | string | Feature type. |
musage | float | Maximum usage of licenses in relation to total license number, expressed in percentages. |
hu | float | Hours used. |
mu | integer | Maximum licenses used count for given date. |
hb | float | Hours borrowed. |
mb | integer | Maximum licenses borrowed count for a given date. |
code | integer | Error code if success equals false, null otherwise. |
totalCount | integer | Total number of rows returned. |
Obtaining information about usage per user for a license server
You can easily fetch metrics about usage per user for a single license server by sending the following HTTP request.
GET /api/v1/report/license-server/${licenseServerId}/usage-per-user/${returnType}?sd=${startDate}&ed=${endDate}&grat=${granularity}$(additional parameters, as needed)
where $ indicates a variable value that you can replace with a value that best suits your needs. The possible parameters are described below.
Parameter | Required | Type | Description |
---|---|---|---|
${licenseServerId} | Yes | integer/string | ID of a single license server or "all" if information about all license servers is requested. |
${returnType} | Yes | string | Specifies the format in which license usage data will be returned. The format can be one of the following: json, csv, xls, xlsx, pdf. |
sd | Yes | string | Specifies the start date for which the report will be generated in YYYY-MM-DD format; for example, 2017-05-20. |
ed | Yes | string | Specifies the end date for which the report will be generated in YYYY-MM-DD format; for example, 2017-05-27. |
grat | Yes | integer | Specifies granularity of the returned data, which can be one of the following:
|
agrt | No | integer | Specifies aggregation type of the returned data. Aggregation type can be one of the following:
By default data is aggregated by username and hostname. |
rn | No | string | Specifies the name of the report that will be displayed once the report has been exported to PDF or XLS/XLSX. For CSV and JSON formats this parameter will be ignored. |
filter | No | json/string | Applies filtering license usage data on all fields. (See this section for more format-specific information.) |
fieldsVisibility | No | json/string | Specifies field visibility settings. (See the this section for more information.) Note that the order of the settings you make is important – when exported, the fields will be visible in exactly the same order you specify here. |
limit | No | integer | Determines the maximum number of data records that can be returned. The value must be greater than zero. |
offset | No | integer | Specifies the offset of the first row to return. |
orderBy | No | string | Specifies the field by which you want to order your data records. The field name can be one of the following: fud | un | ugn | hn | hgn | lsn | fns | fv | ftype | musage | hu | mu | hb | mb (See this section for more field-specific information.) If orderBy is provided, orderDirection is mandatory. |
orderDirection | No | string | Determines whether the sorting results will be displayed in ascending (ASC) or descending (DESC) order. If orderDirection is provided, orderBy is mandatory. |
If your request is successful, you should see a response similar to the response given above for usage per user for a feature.