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 Denials endpoint delivers license usage metrics specific to Denials, allowing you to see exactly
...
License Statistics API lets you generate data from the Denials report. This report shows how many license checkout requests were denied and how often the denials took place.
Obtaining information about checkout denials
If you want to retrieve information about denials for username and hostname, we recommend that you use the following URL request templateYou can easily list denials for given feature that took place by sending the following HTTP request.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
GET /api/v1/report/denialsfeature/${featureId}/denials/${returnType}?sd=${startDateYYYY-MM-DD}&ed=${endDateYYYY-MM-DD}&(additional parameters, as needed) |
where :- $ $ indicates a variable value that you can replace with an appropriate value, as needed- a value that best suits your needs. The possible parameters are as follows:described below.
Parameter | Required | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
${featureId} | Yes | integer | Specifies feature-specific parametersInternal License Statistics identification of the feature for which you want to view denied requests. | ||||||||||||||||
${returnType} | Yes | string | Specifies the format in which license usage data should be returned. The format can be one of the following: json, csv, xls or pdfStandard format option. See Making an API request for details. | ||||||||||||||||
sd | Yes | stringdate | Specifies starting Start date from for which you want to generate the report. The date and time format is as follows: YYYY-MM-DD, for example, 2015-01-20. | ||||||||||||||||
ed | Yes | stringdate | Specifies end End date from for which you want to generate the report. Date format as above. Date The date is inclusive, meaning that all data from the a particular day will be included in the report. | ||||||||||||||||
fieldsVisibilitystandard report options | No | json/string | Specifies field visibility settings, for example:
where number "1" indicates that a specific field is visible. | ||||||||||||||||
rn | No | string | Specifies the name of the report that will be displayed once the report has been exported to PDF or Excel. | ||||||||||||||||
filter | No | json/string | Applies filtering license usage data on all fields. To filter by string column, use the following format:
To filter by numeric column, use the following format:
| ||||||||||||||||
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: un, hn, ldt, ldtc. | ||||||||||||||||
orderDirection | No | string | Determines whether the sorting results will be displayed in ascending (ASC) or descending (DESC) order. |
If your request is successful, you should see a response similar to the following:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
success: true,
msg: ${message},
data: [{
"un": ${userName},
"hn": ${hostName},
"ldt": ${licenseDenialTime},
"ldtc": ${licenseDenialTotalCount}
}]
} |
where the response fields can be explained as follows:
...
uid
...
integer
...
User Id.
...
un
...
string
...
Username.
...
hn
...
string
...
Hostname.
...
ldt
...
string
...
License Denial Time in YYYY-MM-DD HH:MM format
...
ldtc
...
string
...
License Denial Total Count
...
msg
...
string
...
Error message returned on failure.
...
success
...
boolean
...
This field indicates that the API request was successfully processed.
various | See Making an API request for details. |
Response
On success, report will contain one row for each denial, from the given date range. Each row consists of the following columns.
Column | Full name | Type | Description | Visible by default in export |
---|---|---|---|---|
ldt | Date | date and time | Time when the denial took place. | Yes |
ldtc | Denials | integer | Number of denied licenses. | Yes |
un | User | string | Name of the denied user. | Yes |
hn | Host | string | Host from which the denied user tried to check out the license. | Yes |
Note that the order in the table is the default order of the columns in the exported file.
Example 1
The following example shows a command that lets you obtain information about denials for feature "3" over a specified time period.Example 1For example, say you would like to view denials for feature 3 over some period of time. To generate such data, enter a command that is similar to the following:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
curl --data "sd=2015-01-01" --data "ed=2015-01-02" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/denialsfeature/3/denials/json" |
Example 2
Let's assume you want to see The following example shows a command that lets you obtain information about all denials for feature "3" over a specified time period, with data ordered by username over a specific period of time. To do this, enter a command similar to the following:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
curl --data "orderBy=un" --data "orderDirection=ASC" --data "sd=2015-01-01" --data "ed=2015-01-02" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/denialsfeature/3/denials/json" |
Example 3
Let's assume you're interested in viewing the The following example shows a command that lets you view the first 100 denials for feature "3" over a specific specified time period of time. To do this, enter a command that is similar to the following:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
curl --data "limit=100" --data "offset=0" --data "sd=2015-01-01" --data "ed=2015-01-02" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/denialsfeature/3/denials/json" |
Sample script
...
You can also put parameters directly into the URL. For the above example, the command would be similar to the following.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
curl -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/denials/json?limit=100&offset=0&sd=2014-12-01&ed=2015-01-02" |
Obtaining information about grouped checkout denials
...
You can easily list the cumulative number of denials for a given feature per fixed time period by sending the following HTTP request.If you want to retrieve information about denials for username and hostname, we recommend that you use the following URL request template.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
GET /api/v1/report/denialsfeature/grouped/${featureId}/denials/grouped/${returnType}?sd=${startDate}&ed=${endDate}&grat=${granularity}&(additional parameters, as needed) |
where :- $ $ indicates a variable value that you can replace with an appropriate value, as needed- a value that best suits your needs. The possible parameters are as follows: described below.
Parameter | Required | Type | Description | |||||
---|---|---|---|---|---|---|---|---|
${featureId} | Yes | integer | Specifies feature-specific parametersInternal License Statistics identification of the feature for which you want to view grouped checkout denials. | |||||
${returnType} | Yes | string | Specifies the format in which license usage data should be returned. The format can be one of the following: json, csv, xls or pdfStandard format option. See Making an API request for details. | |||||
sd | Yes | stringdate | Specifies starting Start date from which you want to generate the report. The date and time format is as follows: YYYY-MM-DD, for example, 2015-01-20. | |||||
ed | Yes | stringdate | Specifies endEnd date from which you want to generate the report. | Date format as above. DateThe date is inclusive, meaning that all data from | thea particular day will be included in the report. | |||
grat | Yes | integer | Specifies granularity of the returned data, which can be one of the following:
| fieldsVisibility | No | json/string | Specifies field visibility settings, for example:enumeration | Period type the result is aggregated for. See granularity descriptions for further details |
standard report options | No | various | See Making an API request for details. |
Response
On success, this report will contain one row for each period (e.g., each day or week) from the specified date range. Each row consists of the following columns.
Column | Full name | Type | Description | Visible by default in export |
---|---|---|---|---|
ldt | Date | various | The time period. Format depends on granularity. | Yes |
ldtc | Denials | string | Cumulative number of denials licenses in the time period for the feature. | Yes |
Note that the order in the table is the default order of the columns in the exported file.
Example 1
The following example shows a command that obtains information about denials for feature "3" grouped by month.
Code Block | ||||||
---|---|---|---|---|---|---|
|
...
{"un": "1", "hn": "1", "ldt": "1", "ldtc":"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.
curl --data "sd=2015-01-01" --data "ed=2015-01-02" --data "grat=3" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/denials/grouped/json" |
Example 2
The following example shows a command that lets you see all denials grouped by quarter for feature "3" ordered by the total denial count from highest to lowest.
...
Applies filtering license usage data on all fields.
...
Code Block | ||||||
---|---|---|---|---|---|---|
|
...
[
{
"type": "string",
"field": "${un | hn | ldt}",
"value": "${value}"
}
]
curl --data "orderBy=ldtc" --data "orderDirection=DESC" --data "sd=2014-01-01" --data "ed=2015-01-01" --data "grat=2" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/denials/grouped/json" |
Example 3
The following example shows a command that lets you view the first 100 denials for feature "3" over a specific time period, grouped by hour.
...
Code Block | ||||
---|---|---|---|---|
|
...
[
{
"type": "numeric",
"comparison": "${gt | lt | eq}",
"field": "${ldtc}",
"value": "${value}"
}
]
| |||
curl --data "limit=100" --data "offset=0" --data "sd=2013-01-01" --data "ed=2015-01-02" --data "grat=6" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/denials/grouped/json" |
You can also put parameters directly into the URL. For the above example, the command would look like the following:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
curl -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/denials/grouped/json?limit=5&offset=2&sd=2013-01-01&ed=2015-01-02&grat=6" |
...
...
Specifies the field by which you want to order your data records. The field name can be one of the following: un, hn, ldt, ldtc.
...
If your request is successful, you should see a response similar to the following:
...