User History API

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.

Showing sessions at a specific point in time

You can easily fetch metrics about usage history at a particular point in time by sending the following HTTP request.

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.

{"un": "1", "hn": "1", "sst": "1", "set": "1"}

[{"value": intOrString, "field": "${fid | fns | fv | ftype | lsid | lsn | vn | gtn}"}]

uid, un, hn, sst, set

Response

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

{
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 1

The following example shows a command that lets you obtain information about all sessions for feature "3" at a specific time point.

curl --data-urlencode "sdt=2015-10-30 00:00" -H "X-Auth-token: token" "http://yourdomain/api/v1/report/feature/3/user-history/json"

Example 2

The following example shows a command that lets you obtain statistics about all sessions for feature "3" at a specific time point.

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"

Example 3

The following example shows a command that lets you view the first 100 sessions for feature "3" at a specific time point.

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.

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

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.

{"un": "1", "hn": "1", "sst": "1", "set": "1"}

[{"value": intOrString, "field": "${un | hn | sst | set}"}]

uid, un, hn, sst, set 

Response

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

{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 1

The following example shows a command that lets you view all sessions for feature "3" for a given time period.

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 2

The following example shows a command that lets you see all sessions for feature "3" for a given time period and orders the data by username.

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 3

The following example shows a command that lets you view the first 100 sessions for feature "3" over a specific time period.

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

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.

$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?ssd=2016-02-03&sed=2016-02-10" -Headers @{"X-Auth-token"="$($token)"} -OutFile "UserHistoryForPeriod-$($features.data.fid[$i]).pdf"
}