Page History

You can view tool license usage details by calling the License Usage API. The API reads the ls_access.log.yyyy-MM-dd file stored in the DTP logs folder and returns information for the specified period. By default, logs are stored for the last 90 days. See Configuring License Server for information about changing how long logs are stored.

...

You can use basic authentication or OIDC to authenticate. See "Authentication" on the See Using DTP REST APIs page for more information about using basic authentication and and Configuring OpenID Connect for more information about using OIDC.

...

Table of Content Zone

maxLevel	2
minLevel	2
location	top

/toolsUsage

This endpoint returns summary information about tool usage.

URL

No Format
<protocol><PROTOCOL>://<host><HOST>:<port><PORT>/licenseserver/usage/api/v1.0/toolsUsage

Parameters
Anchor
common-license-usage-api-params
common-license-usage-api-params

The following table describes the parameters common to all endpoints in the API.

Parameter Description Type Required

startDate

Specifies the date of the first record to include in the response.

By default, the first date in the log is included.

Format: yyyy-MM-dd

string

Optional

endDate

Specifies the date of the first record after the start date to exclude from the response.

By default, no end date is specified.

Format: yyyy-MM-dd

string

Optional

Response Data

The response is an array of tools and information about the tool usage. The following table describes the response data.

Field		Description	Type
`featuresAtMaxConcurrentLicenseTime`		The features in use at `maxConcurrentLicenseTime`.	array of objects
	`count`	Number of license token requests served for the feature.	integer
	`feature`	Name of the feature for which the license was requested.	string
`maxConcurrentLicenseCount`		The maximum number of license tokens used for the tool at any point in time.	integer
`maxConcurrentLicenseTime`		Date and time of the most recent count of license tokens.	string
`tool`		Name of the tool.	string
`uniqueHostCount`		The number of unique host names across the entire time period.	integer
`uniqueUserCount`		The number of unique users across the entire time period.	integer
`usageHours`		The total amount of time for which license tokens were used. The returned value is an aggregate across users and machines on which the tool is hosted.	float

Example Request

The following example returns tool usage information for March 1, 2020.

No Format
https://myserver:8443/licenseserver/usage/api/v1.0/toolsUsage?startDate=2020-03-01&endDate=2020-03-2

Example Response

The following response shows that one Parasoft Jtest user requested a license for several features for a short period of time.

Code Block

language	js

[
    {
        "featuresAtMaxConcurrentLicenseTime": [
            {
                "count": 1,
                "feature": "Automation"
            },
            {
                "count": 1,
                "feature": "Change Based Testing"
            },
            {
                "count": 1,
                "feature": "Coding Standards"
            },
            {
                "count": 1,
                "feature": "Coverage"
            },
            {
                "count": 1,
                "feature": "Desktop Command Line"
            },
            {
                "count": 1,
                "feature": "Flow Analysis"
            },
            {
                "count": 1,
                "feature": "Unit Test"
            }
        ],
        "maxConcurrentLicenseCount": 1,
        "maxConcurrentLicenseTime": "2020-03-01T20:18:21.369",
        "tool": "jtest!",
        "uniqueHostCount": 1,
        "uniqueUserCount": 1,
        "usageHours": 0.0025158333333333335
    }
]

/featuresUsage

This endpoint returns details about feature usage.

URL

No Format
<protocol><PROTOCOL>://<host><HOST>:<port><PORT>/licenseserver/usage/api/v1.0/featuresUsage

Parameters

This endpoint supports the common API parameters.

Response Data

The response is an array of features and information about the feature usage. The following table describes the response data.

Field		Description	Type
`features`		List of features that have been used at least once.	array of strings
	`<feature_name>`	Name of feature used. Contact your Parasoft representative to learn more about available features for your tool.	string
`tool`		Name of the tool.	string

Example Request

The following example returns feature usage information for March 1, 2020.

No Format
https://myserver:8443/licenseserver/usage/api/v1.0/featuresUsage?startDate=2020-03-01&endDate=2020-03-2

Example Response

The following response shows that several Parasoft Jtest features were used at least once within the specified time start and end dates.

Code Block

language	js

[
    {
        "features": [
            "Automation",
            "Change Based Testing",
            "Coding Standards",
            "Coverage",
            "Desktop Command Line",
            "Flow Analysis",
            "Unit Test"
        ],
        "tool": "jtest!"
    }
]

/licenseUsage

This endpoint returns an array showing license usage, including features used, tools, and usage duration, per user.

URL

No Format
<protocol><PROTOCOL>://<host><HOST>:<port><PORT>/licenseserver/usage/api/v1.0/licenseUsage

Parameters

This endpoint supports the common API parameters.

Response Data

The response is an array of objects that describe license usage.

Field		Description	Type
`features`		List of features enabled by the license.	array of strings
	`<feature_name>`	Name of feature used. Contact your Parasoft representative to learn more about available features for your tool.
`tool`		Name of the tool that consumed a license.	string
`toolVersion`		Version of the tool.	string
`usageHours`		Total number of hours the license for the tool was used by the user.	float
`user`		Host machine from which the tool was executed and user name that requested the license.	object
	`hostname`	Name of the machine from which the tool was executed.	string
	`name`	User name of the tool user that requested the license token.	string

Example Request

The following example returns license usage information for March 1, 2020.

No Format
https://myserver:8443/licenseserver/usage/api/v1.0/licenseUsage?startDate=2020-03-01&endDate=2020-03-2

Example Response

The following response shows that the user "devtest" used a Jtest license with several features on a machine called "lin-dtp-vm2" for a short period of time.

Code Block

language	js

[
    {
        "features": [
            "Automation",
            "Change Based Testing",
            "Coding Standards",
            "Coverage",
            "Desktop Command Line",
            "Flow Analysis",
            "Unit Test"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4",
        "usageHours": 0.0025158333333333335,
        "user": {
            "hostName": "lin-dtp-vm2",
            "name": "devtest"
        }
    }
]

/licenseRejection

This endpoint returns an array of objects showing license requests that we were rejected by the server.

URL

No Format
<protocol><PROTOCOL>://<host><HOST>:<port><PORT>/licenseserver/usage/api/v1.0/licenseRejection

Parameters

This endpoint supports the common API parameters.

Response Data

The response is an array of objects that describe the license request rejections that have been logged.

Field Description Type

noMoreTokens Lists the instances when a license request was rejected because no more tokens were available. array of objects

requestKey License request properties for which license have been rejected. object

Anchor

	lic-reject-resp-reqFeat-field
	lic-reject-resp-reqFeat-field

requestedFeatures

Lists the features that were requested for the tool. When a license request from a tool is made, the request applies to all tools that the user attempted to enable in the .properties file or UI configuration.

array of strings

<feature_name>

Anchor

	lic-reject-featname-field
	lic-reject-featname-field

Name of feature requested. Contact your Parasoft representative to learn more about available features for your tool.

string

Anchor

	lic-reject-resp-field-tool
	lic-reject-resp-field-tool

tool

Name of the tool for which the license request was rejected.

string

Anchor

	lic-reject-resp-toolver-field
	lic-reject-resp-toolver-field

toolVersion

Version of the tool.

string

responseStatistics

Statistical information about the rejected license requests.

object

noMoreTokensCount Number of times the license request was rejected because no more license tokens were available. integer

noMoreTokensUserCount Number of users that made license requests that were rejected because no more license tokens were available. integer

noMoreTokensUsers Lists information about the users for whom license requests were rejected. array of objects

noMoreTokensCount Number of times the user requested a license. integer

noMoreTokensTime List of timestamps marking when the user requested the license. array of strings

<timestamp>

Anchor

	lic-reject-timestamp-string
	lic-reject-timestamp-string

Date and time of when the license tokens were requested. Default format: yyyy yyyy-MM-dd h:m:s:ms

string

user

Anchor

	lic-reject-resp-user-field
	lic-reject-resp-user-field

Host machine from which the rejected license was requested and user name username that requested the license.

object

hostName

Anchor

	lic-reject-resp-hostname-field
	lic-reject-resp-hostname-field

Name of the machine from which the license was requested.

string

name

Anchor

	lic-reject-resp-name-field
	lic-reject-resp-name-field

User name of the tool user that requested the license token.

string

noFeatures Lists the instances when a license request was rejected because one or more of the features requested were missing from the license. In these cases, users can still use the license token for the features enabled per their license agreement. array of objects

requestKey License request properties for which license have been rejected. array of objects

grantedFeatures Names of features for which a license token was available. array of strings

<feature_name> See feature_name See feature_name

requestedNoFeatures List of features that were missing from the license. array of strings

<feature_name> See feature_name See feature_name

tool See tool See tool

toolVersion See toolVersion See toolVersion

responseStatistics Statistical information about the rejected license requests. object

noFeaturesCount Number of times the license request was rejected because the requested features were missing from the license. integer

noFeaturesUserCount Number of users that made license requests that were rejected because the requested features were missing from the license. integer

noFeaturesUsers Lists information about the users for whom license requests were rejected. array of objects

noFeaturesCount Number of times the license request was rejected for the specific user because the requested features were missing from the license. integer

noFeaturesTime List of timestamps marking when the user requested the license. array of strings

<timestamp> See timestamp See timestamp

user See user See user

hostName See hostName See hostName

name See name See name

requestDenied Lists the instances when a license request was rejected because the administrator configured license tokens requests to exclude access for the specific user name, host name, or group (see Filtering License Access). array of objects

requestKey License request properties for which license have been rejected. array of objects

requestedFeatures See requestedFeatures See requestedFeatures

tool See tool See tool

toolVersion See toolVersion See toolVersion

responseStatistics Statistical information about the rejected license requests.

requestsDeniedCount Number of times the license request was denied. integer

requestDeniedUserCount Number of users for whom license requests were denied. integer

requestDeniedUsers Lists information about the users for whom license requests were denied. array of objects

requestDeniedCount Number of times the license request was denied for the specific user. integer

requestDeniedTime List of timestamps marking when the user requested the license. array of strings

<timestamp> See timestamp See timestamp

user See user

hostName See hostName See hostName

name See name See name

Example Request

No Format
https://myserver:8443/licenseserver/usage/api/v1.0/licenseRejection

Example Response

Code Block

language	js

{
  "noFeatures": [
    {
      "requestKey": {
        "grantedFeatures": [
          "Automation",
          "Change Based Testing",
          "Coding Standards",
          "Coverage"
        ],
        "requestedNoFeatures": [
          "CWE Rules",
          "DTP Publish",
          "Desktop Command Line",
          "Flow Analysis",
          "OWASP Rules",
          "PCI DSS Rules",
          "Security Rules",
          "Unit Test"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noFeaturesCount": 4,
        "noFeaturesUserCount": 1,
        "noFeaturesUsers": [{
          "noFeaturesCount": 4,
          "noFeaturesTime": [
            "2020-02-12 14:05:08.951",
            "2020-02-12 14:19:08.959",
            "2020-02-12 14:33:08.927",
            "2020-02-12 14:47:08.944"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "grantedFeatures": [
          "Automation",
          "Change Based Testing",
          "Coding Standards",
          "Coverage"
        ],
        "requestedNoFeatures": [
          "CWE Rules",
          "DTP Publish",
          "Flow Analysis",
          "OWASP Rules",
          "PCI DSS Rules",
          "Security Rules",
          "Unit Test"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noFeaturesCount": 10,
        "noFeaturesUserCount": 1,
        "noFeaturesUsers": [{
          "noFeaturesCount": 10,
          "noFeaturesTime": [
            "2020-02-12 15:00:12.015",
            "2020-02-12 15:00:15.364",
            "2020-02-12 15:00:33.480",
            "2020-02-12 15:01:08.924",
            "2020-02-12 15:15:08.953",
            "2020-02-12 15:21:09.053",
            "2020-02-12 15:35:09.158",
            "2020-02-12 15:42:09.243",
            "2020-02-12 15:56:09.369",
            "2020-02-12 16:10:09.374"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "grantedFeatures": [
          "Command Line",
          "Jtest Connect",
          "Message Packs",
          "RuleWizard",
          "SOA",
          "Stub Desktop",
          "Stub Server",
          "Web"
        ],
        "requestedNoFeatures": ["Server API Enabled"],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "noFeaturesCount": 10,
        "noFeaturesUserCount": 1,
        "noFeaturesUsers": [{
          "noFeaturesCount": 10,
          "noFeaturesTime": [
            "2020-02-12 13:39:35.481",
            "2020-02-12 13:39:35.506",
            "2020-02-12 13:40:05.580",
            "2020-02-12 13:40:05.630",
            "2020-02-12 13:40:06.692",
            "2020-02-12 13:40:06.708",
            "2020-02-12 13:40:31.765",
            "2020-02-12 13:40:31.781",
            "2020-02-12 13:40:55.839",
            "2020-02-12 13:40:55.854"
          ],
          "user": {
            "hostName": "caprica",
            "name": "modtest"
          }
        }]
      }
    }
  ],
  "noMoreTokens": [
    {
      "requestKey": {
        "requestedFeatures": [],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noMoreTokensCount": 4,
        "noMoreTokensUserCount": 1,
        "noMoreTokensUsers": [{
          "noMoreTokensCount": 4,
          "noMoreTokensTime": [
            "2020-02-12 21:46:09.516",
            "2020-02-12 22:00:09.534",
            "2020-02-12 22:14:09.573",
            "2020-02-12 22:28:09.578"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "requestedFeatures": [
          "Automation",
          "CWE Rules",
          "Change Based Testing",
          "Coding Standards",
          "Coverage",
          "DTP Publish",
          "Desktop Command Line",
          "Flow Analysis",
          "OWASP Rules",
          "PCI DSS Rules",
          "Security Rules",
          "Unit Test",
          "Unit Test Bulk Creation",
          "Unit Test Spring Framework"
        ],
        "tool": "jtest!",
        "toolVersion": "10.4"
      },
      "responseStatistics": {
        "noMoreTokensCount": 3,
        "noMoreTokensUserCount": 1,
        "noMoreTokensUsers": [{
          "noMoreTokensCount": 3,
          "noMoreTokensTime": [
            "2020-02-12 12:00:46.576",
            "2020-02-12 12:00:46.840",
            "2020-02-12 12:01:17.713"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    },
    {
      "requestKey": {
        "requestedFeatures": ["Server API Enabled"],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "noMoreTokensCount": 4,
        "noMoreTokensUserCount": 1,
        "noMoreTokensUsers": [{
          "noMoreTokensCount": 4,
          "noMoreTokensTime": [
            "2020-02-12 13:46:30.425",
            "2020-02-12 13:46:30.463",
            "2020-02-12 13:47:06.557",
            "2020-02-12 13:47:06.579"
          ],
          "user": {
            "hostName": "home",
            "name": "kprzybyla"
          }
        }]
      }
    }
  ],
  "requestDenied": [
    {
      "requestKey": {
        "requestedFeatures": [],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "requestDeniedCount": 10,
        "requestDeniedUserCount": 2,
        "requestDeniedUsers": [
          {
            "requestDeniedCount": 2,
            "requestDeniedTime": [
              "2020-02-12 13:46:30.447",
              "2020-02-12 13:47:06.567"
            ],
            "user": {
              "hostName": "home",
              "name": "kprzybyla"
            }
          },
          {
            "requestDeniedCount": 8,
            "requestDeniedTime": [
              "2020-02-12 13:21:23.734",
              "2020-02-12 13:21:38.810",
              "2020-02-12 13:22:36.874",
              "2020-02-12 13:32:58.201",
              "2020-02-12 13:33:24.331",
              "2020-02-12 13:34:23.410",
              "2020-02-12 13:34:27.483",
              "2020-02-12 13:34:35.555"
            ],
            "user": {
              "hostName": "caprica",
              "name": "modtest"
            }
          }
        ]
      }
    },
    {
      "requestKey": {
        "requestedFeatures": ["Server API Enabled"],
        "tool": "SOAtest",
        "toolVersion": "9.10"
      },
      "responseStatistics": {
        "requestDeniedCount": 6,
        "requestDeniedUserCount": 1,
        "requestDeniedUsers": [{
          "requestDeniedCount": 6,
          "requestDeniedTime": [
            "2020-02-12 13:37:30.630",
            "2020-02-12 13:37:30.668",
            "2020-02-12 13:38:13.751",
            "2020-02-12 13:38:13.773",
            "2020-02-12 13:38:50.842",
            "2020-02-12 13:38:50.857"
          ],
          "user": {
            "hostName": "caprica",
            "name": "modtest"
          }
        }]
      }
    }
  ]
}

...

You can call the API from the SwaggerUI shipped withLicense Server, DTP, which the SwaggerUI shipped with DTP, which provides a point-and-click interface for viewing license usage information. The The SwaggerUI is available after logging in. No additional authentication is required.

Open the License Server home page.
Choose Management> Go to Management > Tools Usage to access the API.

...

Paste the URL into a browser bar and add any additional queries.

No Format
http://<host><HOST>/licenseserver/usage/api/v1.0/toolsUsage?startDate=<yyyy-MM-dd>&endDate=<yyyy-MM-dd>

Press the Return key to query the endpoint.

...

Page tree

Versions Compared

Old Version 1

New Version Current

Key

/toolsUsage

URL

Parameters
Anchor
common-license-usage-api-params
common-license-usage-api-params

Response Data

Example Request

Example Response

/featuresUsage

URL

Parameters

Response Data

Example Request

Example Response

/licenseUsage

URL

Parameters

Response Data

Example Request

Example Response

/licenseRejection

URL

Parameters

Response Data

Example Request

Example Response

Page tree

Page History

Versions Compared

Old Version 1

New Version Current

Key

/toolsUsage

URL

Parameters Anchorcommon-license-usage-api-paramscommon-license-usage-api-params

Response Data

Example Request

Example Response

/featuresUsage

URL

Parameters

Response Data

Example Request

Example Response

/licenseUsage

URL

Parameters

Response Data

Example Request

Example Response

/licenseRejection

URL

Parameters

Response Data

Example Request

Example Response

Parameters
Anchor
common-license-usage-api-params
common-license-usage-api-params