Warning |
---|
This page refers to functionality that has been removed from License Statistics. This information no longer applies to License Statistics v6.3 and newer. |
The Feature Utilization endpoint delivers license usage metrics specific to Utilization History, allowing you to monitor the percentage of license usage during any period that usage was trackedLicense Statistics API allows you to generate information from Utilization History.
Obtaining information about utilization history
To retrieve information about utilization history, use following URL request templateYou can easily fetch metrics about the percentage of license usage over a given time period by sending the following HTTP request.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
GET /api/v1/report/feature/${featureId}/utilization-history/${returnType}?sd=${startDateYYYY-MM-DD}&ed=${endDateYYYY-MM-DD}&st=${startTimeHH:MM}&et=${endTimeHH:MM}&incd=${true_or_false}(additional parameters, as needed) |
where :- $ $ indicates a variable value that you can replace with a proper value, according to your needs
- the value that best suits your needs. The possible parameters are as follows:
described below.
Parameter | Required | Type | Description |
---|---|---|---|
${featureId} | Yes | integer |
Internal License Statistics identification of the |
feature for which you want to view utilization history. | ||
${returnType} | Yes | string |
Standard format option. See Making an API request for details. | |
sd | Yes |
date |
Start date |
for which you want to generate the report. |
ed | Yes |
date |
End date |
for which you want to generate the report. The date |
is |
inclusive, meaning that all data from a particular day will be included in the report. | |
st | Yes |
time |
Start time of the time window |
to be applied for each date in a range ("working hours"). |
et | Yes |
time |
End time of the time window |
to be applied for each date in a range ("working hours"). |
incd | No | boolean | Specifies how utilization value should be calculated |
; i.e., whether the downtime periods should be included. If true, the length of |
the entire range will be used as a denominator |
[(days between ${sd} and ${ed} inclusively)*(et-st) |
]. Otherwise, only uptime periods will be used. |
Defaults to false. |
standard report options | No |
Specifies field visibility settings, for example:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{"lc": "1", "lhu": "1", "lutil": "1"} |
where number "1" indicates that a specific field is visible.
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.
If you don't pass this parameter, it will be generated automatically for PDF and XLS types. If provided, it cannot be left empty.
Applies filtering license usage data on all fields.
Use the following format:
Code Block | ||||
---|---|---|---|---|
| ||||
[
{
"type": "numeric",
"comparison": "${gt | lt | eq}",
"field": "${lc | lhu | lutil}",
"value": "${value}"
}
] |
Specifies the field by which you want to order your data records. The field name can be one of the following: ls, lhu, lutil.
If your request is successful, you should see a response similar to the following:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
success: ${success},
msg: ${message},
data: [{
"lc": ${licensesInUse},
"lhu": ${hourUsed},
"lutil": ${utilization}
}],
"code": ${errorCode},
"totalCount": ${totalCount}
} |
where the response fields can be explained as follows:
various | See Making an API request for details. |
Response
On success, report will contain one row for each usage level that occurred in specified time range. That is, if maximum usage for feature was 6, report will include 6 records: one for each number between 1 and 6.
Each row consists of the following columns.
Column | Full name | Type | Description | Visible by default in export |
---|---|---|---|---|
lc | Licenses In Use | integer | Usage level |
lc
integer
that other fields are referring to. | ||||
lhu | Hours Used | float | Number of hours when at least ${lc} licenses were used. | |
lutil | Utilization | float |
Percentage share of time when at least ${lc} licenses where used in percent. Value of ${lhu} is numerator. Denominator value is affected by ${incd} value. |
msg
string
Error message returned on failure.
success
boolean
Indicates whether the API request was successfully processed.
Error code for unsuccessful request.
Total number of all matching results.
Example
Note that the order in the table is the default order of the columns in the exported file.
Example
The following example shows a command that lets you obtain statistics about utilization history for feature "3" over a specific time period, with users' working hours between 9:00 a.m. and 5:00 Say you would like to view utilization history for feature 3 over some period of time and your employees work from 9 to 5. To generate such data, enter a command similar to the following:p.m.
Code Block |
---|
curl --data "sd=2015-01-01" --data "ed=2015-01-02" --data "st=09:00" --data "et=17:00" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/utilization-history/json" |
...