Page History

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 how

With License Statistics API, you can easily generate information about Denials, i.e. about users that were denied access to applications due to checkout requests exceeding the number of available licenses.

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 the username and hostname for each denial, 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

language	js
firstline	1
linenumbers	true

GET /api/v1/report/feature/${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 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

Specifies ID Internal License Statistics identification of the feature for which you want to view denied requests.

${returnType}

Yes

string

Specifies the format in which the 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 YYYY-MM-DD; for example, 2017-01-20.

ed

Yes

stringdate

Specifies end End date from for which you want to generate the report. The date and time format is YYYY-MM-DD; for example, 2017-01-20. The date is inclusive, meaning that all data from a particular day will be included in the report.

fieldsVisibilitystandard report options

No

json/string

Specifies field visibility settings, for example:

Code Block

language	js
firstline	1
linenumbers	true

{"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.

rn

No

string

Specifies the name of the report that will be displayed once the report has been exported to PDF or XLS. For CSV and JSON formats this parameter will be ignored.
If you don't pass this parameter, it will be generated automatically for PDF and XLS types. If provided, it cannot be left empty.

filter

No

json/string

Applies filtering license usage data on all fields.

To filter by string column, use the following format:

Code Block

language	js
firstline	1
linenumbers	true

[
	{ 
		"type": "string",
		"field": "${un | hn | ldt}",
		"value": "${value}"
	}
]

To filter by numeric column, use the following format:

Code Block

language	js
firstline	1

[
	{ 
		"type": "numeric", 
		"comparison": "${gt | lt | eq}", 
		"field": "ldtc",
		"value": "${value}" 
	}
]

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 an ascending (ASC) or a descending (DESC) order.

If your request is successful, you should see a response similar to the following:

Code Block

language	js
firstline	1
linenumbers	true

  {
      success: ${success},
      msg: ${message},
      data: [{
        "un": ${userName},
        "hn": ${hostName},
        "ldt": ${licenseDenialTime},
        "ldtc": ${licenseDenialTotalCount}
      }],
	  "code": ${errorCode},
	  "totalCount": ${totalCount}
  }

where the response fields can be explained as follows:

...

un

...

string

...

Username.

...

hn

...

string

...

Hostname.

...

ldt

...

string

...

License Denial Time in YYYY-MM-DD format

...

ldtc

...

string

...

Total number of denied license checkout requests.

License Denial Total Count.

...

msg

...

string

...

Error message returned on failure.

...

success

...

boolean

...

Indicates whether the API request was successfully processed.

...

Error code if success == false

Error code for unsuccessful request.?

...

Total number of all matching results.

Count of all matching results.

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 1Say you would like to view denials for feature 3 over some period of time. To generate such data, enter a command similar to the following:

Code Block

language	js
firstline	1
linenumbers	true

curl --data "sd=2015-01-01" --data "ed=2015-01-02" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/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 this one:

Code Block

language	js
firstline	1
linenumbers	true

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/feature/3/denials/json"

Example 3

Let's say 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

language	js
firstline	1
linenumbers	true

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/feature/3/denials/json"

Keep in mind that you can also put parameters directly in the URL, f.e for an equivalent of the above:
Keep in mind that you You can also put parameters directly into the URL, e.g. to generate data for . For the above example, the command would look like this:be similar to the following.

Code Block

language	js
firstline	1
linenumbers	true

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

language	js
firstline	1
linenumbers	true

GET /api/v1/report/feature/${featureId}/denials/grouped/${returnType}?sd=${startDate}&ed=${endDate}&grat=${granularity}&(additional parameters, as needed)

where :- $ $ indicates a variable value that you can replace with a proper value, according to your needs
- the possible parameters are as follows: value that best suits your needs. The possible parameters are described below.

stringSpecifies end . The date and time format is YYYY-MM-DD; for example, 2017-01-20granularity

Applies filtering license usage data on all fields.

To filter by string column, use the following format:

Parameter

Required

Type

Description

${featureId}

Yes

integer

Specifies ID Internal License Statistics identification of the feature for which you want to view grouped checkout denials.

${returnType}

Yes

string

Specifies format in which the 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 YYYY-MM-DD; for example, 2017-01-20.

ed

Yes

date

End date from 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.

grat

Yes

integer

Specifies granularity of the returned data, and can be one of the following:

Quarter - 2
Month - 3
Week - 4
Day - 5
Hour - 6

fieldsVisibility

No

json/string

Specifies field visibility settings, for example:

Code Block

language	js
firstline	1
linenumbers	true

{"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.

rn

No

string

Specifies the name of the report that will be displayed once the report has been exported to PDF or XLS. For CSV and JSON formats this parameter will be ignored.
If you don't pass this parameter, it will be generated automatically for PDF and XLS types. If provided, it cannot be left empty.

filter

No

json/string

Code Block

language	js
firstline	1
linenumbers	true

[
	{ 
		"type": "string",
		"field": "ldt",
		"value": "${value}"
	}
]

To filter by numeric column, use the following format:

Code Block

language	js
firstline	1

[
	{ 
		"type": "numeric", 
		"comparison": "${gt | lt | eq}", 
		"field": "ldtc",
		"value": "${value}" 
	}
]

limitNointegerDetermines the maximum number of data records that can be returned. The value must be greater than zero.offsetNointegerSpecifies the offset of the first row to return.orderByNostring

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.

orderDirectionNostringDetermines whether the sorting results will be displayed in ascending (ASC) or descending (DESC) order.

...

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

language	js
firstline	1
linenumbers	true

  {
      success: ${success},
      msg: ${message},
      data: [{
        "ldt": ${licenseDenialTime},
        "ldtc": ${licenseDenialTotalCount}
      }]
  }

where the response fields can be explained as follows:

...

ldt

...

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.

...

ldtc

...

string

...

License Denial Total Count

Total number of denied license checkout requests.

...

msg

...

string

...

Error message returned on failure.

...

success

...

boolean

...

Indicates if the API request was successfully processed.

...

msg

...

string

...

Error message returned on failure.

...

Error code if success == false

Error code for unsuccessful request.?

...

Count of all matching results.

Total number of denied license checkout requests.

Example 1Say you would like to view denials for feature 3 grouped by month. To generate such data, enter a command similar to this one:

Code Block

language	js
firstline	1
linenumbers	true

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

Let's assume you want to The following example shows a command that lets you see all denials grouped by quarter for feature "3, grouped by quarter, " ordered by the total denial count from highest to lowest. To do this, enter a command similar to the following:

Code Block

language	js
firstline	1
linenumbers	true

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

Let's say 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 time period of time, grouped by hour. To do this, enter a command that is similar to the following:

Code Block

language	js
firstline	1
linenumbers	true

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"

Similarly, as in the case of checkout denials, you You can also put parameters directly into the URL, f.e for an equivalent of the above:Keep in mind that you can also put parameters directly into the URL, e.g. to generate data for the above . For the above example, the command would look like thisthe following:

Code Block

language	js
firstline	1
linenumbers	true

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"

...

Page tree

Versions Compared

Old Version 43

New Version Current

Key

Obtaining information about checkout denials

Obtaining information about grouped checkout

denials