| 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 User History endpoint delivers license usage metrics specific to the User History report, allowing you to see statistics for license usage per user, during any period that usage was tracked.
...
You can easily fetch metrics about usage history at a particular point in timeuser session history by sending the following HTTP request.
| Code Block | ||||
|---|---|---|---|---|
| ||||
GET /api/v1/report/feature/${featureId}/user-history/${returnType}?sdt=${sessionDateTime}&(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 | integerSpecifies | feature-specific parametersInternal License Statistics identification of the feature for which you want to view user history. | |||||||||
| ${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. | |||||||||
| sdt | YesNo | string | date and time | Point Specifies point in time for which you want to generate the report. The date is in YYYY-MM-DD HH:MM format; for example, 2017-05-20 11:00. | ||||||||
| fieldsVisibility | 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 XLS. | filter | No | json/string |
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
[{"value": intOrString, "field": "${fid | fns | fv | ftype | lsid | lsn | vn | gtn}"}] |
Specifies the field by which you want to order your data records. The field name can be one of the following:
uid, un, hn, sst, set(See this section for more field-specific information.)
Response
The following code block shows an example result of a successful request.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
success: true,
msg: ${message},
data: [{
uid: ${userId},
un: ${userName},
hn: ${hostName},
sst: ${sessionStartTime},
set: ${sessionEndTime},
il: ${hasUserLdapDetails}
}]
} |
...
| Cannot be used with "ssd" and "sed". | |||
| ssd | No | date | Start date for which the report will be generated. |
| sed | No | date | End date for which the report will be generated. |
| standard report options | No | various | See Making an API request for details. |
Note: Either "sdt" or both "ssd" and "sed" must be specified.
Response
On success, this report will contain:
- if parameter "sdt" was used, one row for each session that started before or at the specified point in time and ended after or upon the specified point in time.
- if parameters "ssd" and "sse" were used, one row for each session that overlaps with the specified time range.
| Field | Full name | Type | Description | Visible by default in export |
|---|---|---|---|---|
| uid | User ID | integer | User ID. |  No |
| un | User | string | Username. |  Yes |
| hn | Host | string | Hostname. | Yes |
| sst | Start Time | date and time | Time when the license was checked out. | Yes |
| set | End Time | date and time/string | Time when the license was checked in, or "Still in use." | Yes |
| tu | Time Used | string | How long the license has been in use. Note that you cannot filter on this field. | Yes |
| uil | User is from LDAP |
...
| Field | Type | Description |
|---|---|---|
| uid | integer | User ID. |
| un | string | Username. |
| hn | string | Hostname. |
| sst | string | Date returned in YYYY-MM-DD HH:MM format; for example, 2017-05-20 11:00. |
| set | string | Date returned in YYYY-MM-DD HH:MM format; for example, 2017-05-20 11:00, "Unknown" or "Still in use". |
| il | boolean | Indicates whether user details have been imported from the LDAP directory. Note that you cannot filter and order data by this field. |
| msg | string | Error message returned on failure. |
| success | boolean | Indicates whether your API request was successfully processed. |
 Unavailable |
Note that order in table is default order of columns in exported file.
Example 1
The following example shows a command that lets you obtain information about all sessions for feature "3" at a specific specified time point.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
curl --data-urlencode "sdt=2015-10-30 00:00" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/user-history/json" |
...
The following example shows a command that lets you obtain statistics about all sessions for feature "3" at a specific specified time point.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
curl --data "orderBy=un" --data "orderDirection=ASC" --data-urlencode "sdt=2015-10-30 00:00" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/user-history/json" |
...
The following example shows a command that lets you view the first 100 sessions for feature "3" at a specific specified time point.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
curl --data "limit=100" --data "offset=0" --data-urlencode "sdt=2015-10-30 00:00" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/user-history/json" |
Sample script
This sample PowerShell 3.0 script serves as a template for generating PDF reports to a file for features with a specific name and for a license server of your choosing. The script saves reports to a file under a filename that follows the pattern: UserHistory-${featureId}.pdf. You can easily adapt this script to any target parameters you'd like to use to generate the desired report. The number of generated PDF files corresponds to the number of features meeting the defined criteria.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
$token = "Yourtoken"
$url = "http://yourdomain/api/v1/report"
$features = Invoke-RestMethod "$($url)/feature/json?fns=FeatureName&lsn=LicenseServerName" -Headers @{"X-Auth-token"="$($token)"}
for ($i=0; $i -lt $features.data.fid.Length; $i++) {
Invoke-RestMethod "$($url)/feature/$($features.data.fid[$i])/user-history/pdf?sdt=2016-02-03 00:00" -Headers @{"X-Auth-token"="$($token)"} -OutFile "UserHistory-$($features.data.fid[$i]).pdf"
} |
Showing sessions for a given time period
You can easily fetch metrics about usage history for a given time period by sending the following HTTP request.
| Code Block | ||||
|---|---|---|---|---|
| ||||
GET /api/v1/report/feature/${featureId}/user-history/${returnType}?ssd=${sessionStartDate}&sed={sessionEndDate}&(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.
...
json |
...
Specifies the start date for which the report will be generated The date is in YYYY-MM-DD format; for example, 2017-05-20.
...
Specifies the end date for which the report will be generated. The date is in YYYY-MM-DD format; for example, 2017-05-27.
...
Specifies field visibility settings, for example:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{"un": "1", "hn": "1", "sst": "1", "set": "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.
...
Applies filtering license usage data on all fields. To filter your data, use the following format.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
[{"value": intOrString, "field": "${un | hn | sst | set}"}] |
...
Specifies the field by which you want to order your data records. The field name can be one of the following:
uid, un, hn, sst, set
(See this section for more field-specific information.)
...
Response
The following code block shows an example result of a successful request.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{success: true, msg: ${message}, data: [
uid: ${userId},
un: ${userName},
hn: ${hostName},
sst: ${sessionStartTime},
set: ${sessionEndTime},
il: ${hasUserLdapDetails}
]} |
where the response fields can be explained as follows.
...
" |
...
Example 4Example 1
The following example shows a command that lets that lets you view all sessions for feature "3" for a given specified time period.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
curl --data "ssd=2015-01-01" --data "sed=2015-01-02" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/user-history/json" |
Example 25
The following example shows a command that lets that lets you see all sessions for feature "3" for a given specified time period, and orders the data by data by username.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
curl --data "orderBy=un" --data "orderDirection=ASC" --data "ssd=2015-01-01" --data "sed=2015-01-02" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/user-history/json" |
Example 36
The following example shows a command that lets that lets you view the first 100 sessions for feature "3" over a specific specified time period.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
curl --data "limit=100" --data "offset=0" --data "ssd=2015-01-01" --data "sed=2015-01-02" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/user-history/json" |
Sample script 1
This sample PowerShell 3.0 script serves as a template for generating PDF reports to a file for features with a specific name and for a license server of your choosing. The script saves reports to a file under a filename that follows the pattern: UserHistory-${featureId}.pdf. You can easily adapt this script to any target parameters you'd like to use to generate the desired report. The number of generated PDF files corresponds to the number of features meeting the defined criteria.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
$token = "Yourtoken"
$url = "http://yourdomain/api/v1/report"
$features = Invoke-RestMethod "$($url)/feature/json?fns=FeatureName&lsn=LicenseServerName" -Headers @{"X-Auth-token"="$($token)"}
for ($i=0; $i -lt $features.data.fid.Length; $i++) {
Invoke-RestMethod "$($url)/feature/$($features.data.fid[$i])/user-history/pdf?sdt=2016-02-03 00:00" -Headers @{"X-Auth-token"="$($token)"} -OutFile "UserHistory-$($features.data.fid[$i]).pdf"
} |
Sample script 2
This sample PowerShell 3.0 script can be used as a template for generating PDF reports to a file for features with a specific name and for a license server of your choosing. The script saves reports to a file under a filename that follows the pattern: UserHistoryForPeriod-${featureId}.pdf. You can easily adapt this script to any target parameters you'd like to use to generate the desired report. The number of generated PDF files corresponds to the number of features meeting the defined criteria.
...