Page History

...

You can easily fetch metrics about the percentage of license usage over a given timeframe time period by sending the following HTTP request.

Code Block

language	js
firstline	1

 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 value that best suits your needs. The possible parameters are described below.

Parameter	Required	Type	Description
${featureId}	Yes	integer

Specifies ID

Internal License Statistics identification of the

feature

feature for which you want to view utilization history.
${returnType}	Yes	string

Specifies the format in which the data should be returned. The format can be one of the following: json, csv, xlsx, or pdf

Standard format option. See Making an API request for details.
sd	Yes

string

date

Specifies the starting

Start date

from

for which you want to generate the report

. The date is in YYYY-MM-DD format; for example, 2017-05-20

.
ed	Yes

string

date

Specifies the end

End date

from

for which you want to generate the report. The date is

in YYYY-MM-DD format; for example, 2017-05-20. The date is

inclusive, meaning that all data from a particular day will be included in the report.
st	Yes

string

time

Specifies the start

Start time of the time window

that

to be applied for each date in a range ("working hours")

in HH:MM format; for example, 09:30

.
et	Yes

string

time

Specifies the end

End time of the time window

that

to be applied for each date in a range ("working hours")

in HH:MM format; for example, 09:30

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

fieldsVisibility

standard report options

No

json/string

Specifies field visibility settings, for example:

Code Block

language	js
firstline	1
linenumbers	true

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

rnNostringSpecifies the name of the report that will be displayed once the report has been exported to PDF or XLSX. 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 XLSX types. If provided, it cannot be left empty.filterNojson/string

Applies filtering license usage data on all fields.

To filter by a numeric column, use the following format.

Code Block

language	js
firstline	1

[
	{ 
		"type": "numeric", 
		"comparison": "${gt | lt | eq}", 
		"field": "${lc | lhu | lutil}",
		"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:

 ls, lhu, lutil

(See this section for more field-specific information.)

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

Response

The following code block shows an example result of a successful request.

Code Block

language	js
firstline	1
linenumbers	true

  {
      success: ${success},
      msg: ${message},
      data: [{
        "lc": ${licensesInUse},
        "lhu": ${hourUsed},
        "lutil": ${utilization}
      }],
	  "code": ${errorCode},
	  "totalCount": ${totalCount}
  }

...

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

...

FieldTypeDescription

lc

integer

Number of licenses

that other fields are referring to.	Yes
lhu	Hours Used	float	Number of hours when at least ${lc} licenses were used.	Yes
lutil	Utilization	float

Share

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 your API request was successfully processed.

codeinteger

Error code for unsuccessful request.

totalCountintegerTotal number of all matching results

Yes

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 p.m.

...

Page tree

Versions Compared

Old Version 7

New Version 8

Key

Example