Define settings for custom license models

When you’re creating a custom license model, use the JSON-formatted rules below to define the behavior and constraints for the model.

The custom license model configuration accepts any combination of behaviours and constraints. Make sure you validate and review that the resulting license model works as expected.

However, there are some minimum recommendations for creating a working license model:

A license model only makes sense if you set a (non-zero) value in either leaseTimeCheckOut or leaseTimeCache in the LeaseTimeBehavior behavior rule. Otherwise license leases expire immediately after they’re created.
In addition, if you don’t specify any sessionAnchors values with the ConcurrentSessions constraint rule, one license seat can be consumed on an unlimited number of devices, which may not be the desired behavior.

Behavior rules

Use these rules to define the behavior of a custom license model.

LeaseTimeBehavior

Define the behavior of license leases, which are created when end users start consuming the license.

Here’s an example rule.

{
   "LeaseTimeBehavior": {
      "leaseTimeCheckOut": 2592000000,
      "refreshTimeCheckOut": 12600000,
      "leaseTimeCache": 7200000,
      "refreshTimeCache": 3600000,
      "incrementModel": "relative",
      "cooldownTime": 0,
      "allowLeaseExtension": true,
      "allowLeaseRelease": true
   }
}

With the example rule above, license leases work as follows:

When an end user is consuming a license offline, the license token is valid for 30 days and the recommended token refresh time is every 3,5 hours after the license lease was issued. In online consumption, the token is valid for 2 hours and the recommended token refresh time is every 1 hour.
When the client application requests for a new token, the new validity end time is counted from the time of the request, and any remaining validity time is ignored.
License leases can be extended. (This means our example license model must also specify the constraint rules that define how the extending is done.)
Licenses can be released, and they become immediately available to other end users after releasing.

Fields:

leaseTimeCheckOut

Define the maximum license token (lease) validity for offline use. This maximum value is also used as a default value if the client application doesn’t request a specific duration.

Format: milliseconds
refreshTimeCheckOut

Define the recommended token refresh time in offline use, counted from the lease issuing time (the iat claim in the license token).

Format: milliseconds
leaseTimeCache

Define the maximum license token (lease) validity for online use. This maximum value is also used as a default value if the client application doesn’t request a specific duration.

Format: milliseconds
refreshTimeCache

Define the recommended token refresh time in online use, counted from the lease issuing time (the iat claim in the license token).

Format: milliseconds
incrementModel

Define how license consumption time is counted when the client application requests for a new license: whether the remaining consumption time is included or ignored.

Possible values:
- relative: The new consumption time is counted starting from the time of the request (remaining consumption time is ignored).
- stack: The new consumption time is added on top of the remaining consumption time.
For example, if the current lease is still valid for 1 hour and the client application requests a new license for 2 hours, with relative the new validity end time is 2 hours from the time of the request, and with stack, 3 hours.

Note: If you want to track use time with the license model, make sure to use the correct value combination together with AggregateUseConstraint.

If empty, relative is used.
cooldownTime

Define the delay after which a license becomes available to other end users after it has been released.

Format: milliseconds

To have a license become available immediately after its release, you can leave out the attribute from the model, or set the value to 0 (or empty or null).
allowLeaseExtension

Define whether or not an existing license lease can be extended.

Possible values:
- true (default)
- false
For a fixed-length lease, set this to false.
allowLeaseRelease

Define whether or not an existing license lease can be released.

Possible values:
- true (default)
- false

licensePoolBehavior

Define whether a new license is added or the existing license is updated when you grant a license and the entitlement already contains a license for the same licensed item.

With this example rule, a new license is added every time.

{
   "licensePoolBehavior": {
      "behavior": ""
   }
}

Fields:

behavior

Define where the seats, use count, and use time are added.

Possible values:
- singlePool: The license credit is added to the existing license.
- operation: A new license is added with the defined license credit.
If empty, operation is used.

licenseLockingBehavior

Define if license locking is used to optimize response times to license consumption requests.

If multiple requests to the same license are received simultaneously, license locking avoids the risk that one of them would exceed the license credit.

This example rule disables license locking.

{
   "licenseLockingBehavior": {
      "lockMode": ""
   }
}

Fields:

lockMode

Define if license locking is used.

Possible values: LOCK_LICENSE

If empty, license locking is not used.

Constraint rules

Use these rules to define the constraints for a custom license model.

ConcurrentSessions

Define the rules for concurrent license consumption, for example, whether an end user can concurrently consume the same license seat from multiple devices.

With “lease anchors”, you define the basis on which lease consumption is counted: based on the devices (hardware) or processes consuming the license, or the external resources or licensed items that are being consumed.

If needed, you can use additional anchors to define what is not counted into license consumption. For example, you could set hardware as a lease anchor and licensed processes as an additional anchor. This combination would be useful when a number of client application processes are created at startup and each one with its own lifecycle, and you don’t want the processes to be counted as separate license sessions.

The following examples illustrate the use of anchors.

Example rule 1: The license can only be consumed on one piece of hardware concurrently (in both online and offline consumption).

{
   "ConcurrentSessions": {
      "maxCache": 1,
      "maxTotal": 1,
      "maxCheckOut": 1,
      "leaseTrackingMode": "IGNORE_LEASE_ID",
      "sessionAnchors": {
         "__objType": "ArrayList",
         "Items": [{
            "__objType": "String",
            "value": "Hardware"
         }]
      }
   }
}

Example rule 2: An unlimited number of processes can be running on the same hardware, and they still count as one consumption of the license. The processes are not counted as separate license sessions.

{
   "ConcurrentSessions": {
      "maxCache": 3,
      "maxTotal": 3,
      "maxCheckOut": 3,
      "sessionAnchors": {
         "__objType": "ArrayList",
         "Items": [{
            "__objType": "String",
            "value": "Hardware"
         }]
      },
      "additionalAnchors": {
         "__objType": "ArrayList",
         "Items": [{
            "__objType": "String",
            "value": "LicensedProcess"
         }]
      }
   }
}

Example rule 3: If multiple processes are running on the same hardware, each process counts as a separate concurrent consumption of the license. The hardware and the processes are all counted as separate license sessions.

{
   "ConcurrentSessions": {
      "maxCache": 3,
      "maxTotal": 3,
      "maxCheckOut": 3,
      "sessionAnchors": {
         "__objType": "ArrayList",
         "Items": [{
               "__objType": "String",
               "value": "Hardware"
            },
            {
               "__objType": "String",
               "value": "LicensedProcess"
            }
         ]
      }
   }
}

Fields:

maxCache

Define the number of concurrent license sessions allowed per user in online use.

For example, if you set this to 1 and sessionAnchors to Hardware, the license can only be consumed on one device at the same time.

Format: positive integers
maxTotal

Define the total number of concurrent license sessions allowed per user.

Format: positive integers
maxCheckOut

Define the number of concurrent license sessions allowed per user in offline use.

Format: positive integers
leaseTrackingMode

Define how lease chaining is used.

When lease chaining is enforced and hardware with a specific identifier gets a license lease (a seat), consecutive requests to refresh the lease must contain the JSON Web Token ID (JTI) of the previous lease.

The JTI (also referred to as leaseId) is expressed as the jti claim in the JWT payload.

Possible values:
- IGNORE_LEASE_ID: Lease chaining is not required.
- USE_LEASE_ID_WHEN_PRESENT: Lease chaining is enabled but not enforced.
- REQUIRE_LEASE_ID: Lease chaining is enforced. The JTI must be provided on license renewal to extend the existing lease, otherwise this is handled as a request for a new lease.
sessionAnchors

Define what the license lease is anchored to.

The anchors define how separate license sessions are identified. The ConcurrentSessions rule’s maximum limits for concurrent sessions are checked against hardware, processes, or licensed resources or items (or a combination of these) depending on the anchors you define.

Possible values:
- Hardware. Anchor consumption to the devices (hardware) consuming the license.
  
  Requires the hw parameter in the license consumption request.
- LicensedProcess. Anchor consumption to the processes (process IDs) consuming the license.
  
  Requires the process parameter in the license consumption request.
  
  If you include this anchor, also include Hardware as an anchor (see the examples above).
- LicensedResource. Anchor consumption to the external resources that are being consumed.
  
  Requires the resource parameter in the license consumption request.
- LicensedItem. Anchor consumption to the aggregated licensed items that are being consumed.
  
  No additional parameters required.
additionalAnchors

Define additional anchors to define what is not counted into separate license sessions.

Possible values:
- LicensedProcess. See description above under sessionAnchors.

SeatCountConstraint

Restrict license consumption based on the license’s seat count.

You can use this both with organizations’ license pools and with personal licenses (where the seat count is 1).

The seat count restriction is enabled in the system by default. If you don’t want to apply this restriction in the license model, include this rule and disable the tracking. In this case, use the other rules to restrict consumption, for example, based on the use count (UseCountConstraint) or use time (AggregateUseConstraint).

With this example rule, license consumption is not restricted based on the seat count.

{
   "SeatCountConstraint": {
      "trackingMode": "NOT_TRACKED"
   }
}

Fields:

trackingMode

Define whether license consumption is restricted based on the license’s seat count.

Possible values:
- TRACKED: Restricted
- NOT_TRACKED: Not restricted
If empty, NOT_TRACKED is used.

AggregateUseConstraint

Define how license use time is recorded. This rule is required for licenses that grant use time.

This rule must be used in combination with the LeaseTimeBehavior constraint, and the correct value depends on what you set in incrementModel in LeaseTimeBehavior.

If you don’t include this rule, use the other rules to restrict consumption, for example, based on the seat count (SeatCountConstraint) or use count (UseCountConstraint).

Your 10Duke Enterprise configuration must have the use time credit feature enabled. Contact the 10Duke Integration Support team if needed.

As an example to illustrate how you can restrict license use based on use time, you could have a photo editing software, and you want licenses that restrict its use based on the total use time allowed during the license validity time. For example, you want to grant access to a customer organization for 1 year and allow them a maximum of 1200 hours of use. If each application session consumes a minimum of 24 hours, the license allows the organization’s users to run a maximum of 50 photo editing sessions in total over the course of a year.

This example rule defines that use time is tracked using the “fair” model. This requires that LeaseTimeBehavior has incrementModel set to relative.

{
   "AggregateUseConstraint": {
      "incrementModel": "fair"
   }
}

Fields:

incrementModel

Possible values:
- fair
  
  Use this value if LeaseTimeBehavior has incrementModel set to relative.
  
  This combination is a fair model because the actual use time is tracked, and a license consumption refresh call adds only the additional time in relation to the original consumption time.
  
  The fair increment model appends the time difference from the last consumption to aggregate time.
  
  Example: A client consumes a license with a 1-day duration. After 2 hours, the client refreshes the license with a new consumption call for another 1-day duration. The addition to aggregate use time at the time of the first call was 1 day. The fair increment that results from the second call adds 2 hours to the aggregated use time.
- append
  
  Use this value if LeaseTimeBehavior has incrementModel set to stack.
  
  With this combination, every license consumption stacks the consumption time on top of the previous value.
  
  The append increment model appends consumption duration time mechanically. It never considers the time difference between consecutive calls and compares that to the consume duration.
  
  Example: A client application consumes a license with a 1-day duration. The client makes a license refresh call after 2 hours. The resulting aggregated use time after the second call is 2 days (mechanically adding a 1-day duration from both calls).

UseCountConstraint

Restrict license consumption by the license’s use count. Each license consumption request must declare the use count to be consumed.

If you don’t include this rule, use the other rules to restrict consumption, for example, based on the seat count (SeatCountConstraint) or use time (AggregateUseConstraint).

Your 10Duke Enterprise configuration must have the use count credit feature enabled. Contact the 10Duke Integration Support team if needed.

For more information on use count licenses, see example use cases and how to provision a use count license.

With this example rule, license consumption is not restricted based on the use count.

{
   "UseCountConstraint": {
      "trackingMode": ""
   }
}

Fields:

trackingMode

Define whether license consumption is restricted based on the license’s use count.

Possible values:
- TRACK_BY_CALLER_CONSUMPTION_COUNT: Track usage based on the count requested by the client application.
- NOT_TRACKED: Not restricted

If the rule is not included or it’s empty, NOT_TRACKED is used.

VersionConstraint

Restrict license consumption to the software versions specified in the license.

When versioning is enforced, the client application must declare in the license consumption request what version of the software is running on the device.

This example rule enforces an exact version matching constraint between the version declared in the consumption call and the version defined in the license.

{
   "VersionConstraint": {
      "versionChecker": "com.tenduke.sdk2.utils.object.ExactVersionMatcher",
      "versionCheckPolicy": "CheckLicenseVersion"
   }
}

Fields:

versionChecker

Define the fully qualified name of the class that implements version checking.

Possible values:
- com.tenduke.sdk2.utils.object.ExactVersionMatcher: Exact matching
- com.tenduke.sdk2.utils.object.RegexVersionMatcher: Regular expression matching
- com.tenduke.sdk2.utils.object.SemanticVersionMatcher: Semantic version (range) matching
versionCheckerPolicy

Define whether versions are checked and from where.

Possible values:
- CheckCreditVersion: Restricting is done based on the location/schema option of the license version in the license credit (in a credit-based deployment).
- CheckLicenseVersion: Restricting is done based on the location/schema option of the license version in the license itself.
- AllowAnyVersion: Allow any version—restricting based on software version is disabled.

IpAddressConstraint

Restrict license consumption based on allowed IP locations (an IP range and/or Geo IP location). This rule is most commonly used to limit license consumption to certain locations.

To use this constraint:

An integration to a third-party API service and IP database is required to resolve the IP location of the calling client application (a commercial license is required).
You must create a license model and product package per region.

This example rule only allows license consumption if the caller’s IP address can be resolved and if it either matches the allowed IP range 212.68.32.0/28-2a00:1450:4010:c03::00/120 or the Geo IP location is Canada.

{
   "IpAddressConstraint": {
      "allowedIpRanges": {
         "__objType": "ArrayList",
         "Items": [{
               "__objType": "String",
               "value": "212.68.32.0/28"
            },
            {
               "__objType": "String",
               "value": "2a00:1450:4010:c03::00/120"
            }
         ]
      },
      "allowedGeoIpLocations": {
         "__objType": "GeolocationBoundaries",
         "boundaries": {
            "__objType": "Iso3166CountryCodeBoundaries",
            "countries": {
               "__objType": "ArrayList",
               "Items": [{
                  "__objType": "String",
                  "value": "CA"
               }]
            }
         },
         "allowUnresolvedGeoIpLocation": "false"
      }
   }
}

Fields:

allowedIpRanges

Define the allowed IP range.

Format: IPv4 or IPv6 address range

Example value: 212.68.32.0/28
allowedGeoIpLocations

Define the country code of the area from which geocoded IP addresses are allowed.

Possible values: ISO 3166 Alpha-2 country codes (the two-character format)

Example value: FI (Finland)
allowUnresolvedGeoIpLocation

Define whether or not license consumption is allowed even if resolving the location fails.

Possible values:
- true
- false

AssignedLicenseConstraint

Use named seats for the licenses.

If you don’t include this rule, the license model uses floating seats: consuming a license doesn’t require a seat reservation.

Example 1: With this rule, a user must have an existing seat reservation to start consuming a license. After a seat has been assigned to a certain user, it cannot be reassigned to another user.

{
   "AssignedLicenseConstraint": {
      "allowLazyReservation": false,
      "seatReservationPolicy": "UNLIMITED_RESERVATIONS",
      "requiredAssignmentReservationType": "reserved",
      "reservationReleaseAllowed": false
   }
}

Example 2: Like above, a user must have an existing seat reservation to start consuming a license. However, this rule allows seats to be reassigned from one user to another, but only for the limited number of times defined in the product package.

{
   "AssignedLicenseConstraint": {
      "allowLazyReservation": false,
      "seatReservationPolicy": "LIMITED_RESERVATIONS",
      "requiredAssignmentReservationType": "reserved",
      "reservationReleaseAllowed": true
   }
}

Fields:

allowLazyReservation

Define whether a user can start consuming a license without having an existing reservation, and a reservation is automatically created the first time the user consumes the license.

Possible values:
- true
- false
seatReservationPolicy

Define whether there are limitations to making seat reservations.

Possible values:
- UNLIMITED_RESERVATIONS: Unlimited seat reservations are allowed.
- LIMITED_RESERVATIONS: Seat reservations are allowed for a limited number of times.
  
  You define the limit itself in the product package. In each product package that uses this license model, define a seat reservation count multiplier for each licensed item.
requiredAssignmentReservationType

Define that a user must have a seat reservation to be able to consume a license.

Possible values: reserved
reservationReleaseAllowed

Define if releasing a seat reservation is allowed, that is, whether license seats can be reassigned from one user to another.

Possible values:
- true
- false

UtilizationConstraint

Allow over-usage of licenses by extending their seat count, use time, or use count.

Here are two example rules that allow over-usage of license seats.

Example 1: This rule allows over-usage by two seats on top of the initial license seats granted.

{
   "UtilizationConstraint": {
      "itemCountExtUnit": "count",
      "itemCountExt": 2
   }
}

Example 2: This rule allows over-usage by 2.5% on top of the initial license seats granted. For example, a license with 100 seats could be extended with three seats (2.5 rounded up).

{
   "UtilizationConstraint": {
      "itemCountExtUnit": "percentage",
      "itemCountExt": 2.5
   }
}

Fields:

itemCountExt

Define how much a license’s seat count is increased after the original quantity has been reached.

Depending on the value of itemCountExtUnit, define either the number of extra seats or a percentage of the license’s seat count to be allowed for over-usage.

If you use a decimal percentage, the system rounds up the resulting value (itemCountExt × the total number of license seats granted) to the nearest integer from the half point value of 0.5.

Format: Decimal number

Example value: 2.5
itemCountExtUnit

Define whether license over-usage based on seat count is defined as a number of extra seats or as a percentage of the license’s seat count.

Possible values:
- count
- percentage
If empty, percentage is used.
useTimeExt

Define how much a license’s use time is extended after the original time has been reached.

Depending on the value of useTimeExtUnit, define either the amount of extra time (in milliseconds) or the percentage of the total license use time to be added.

If you use a decimal percentage, the system rounds up the resulting value (useTimeExt × the total amount of license use time granted) to the nearest integer from the half point value of 0.5.

Format: Decimal number

Example value: 2.5
useTimeExtUnit

Define whether license over-usage based on use time is defined as an amount of time or as a percentage of the total license use time.

Possible values:
- count
- percentage
If empty, percentage is used.
useCountExt

Define how much a license’s use count is increased after the original count has been reached.

Depending on the value of useCountExtUnit, define either the number of extra uses or a percentage of the license’s total use count to be added.

If you use a decimal percentage, the system rounds up the resulting value (useCountExt × the total number of license units granted) to the nearest integer from the half point value of 0.5.

Format: Decimal number

Example value: 2.5
useCountExtUnit

Define whether license over-usage based on the use count is defined as a number or as a percentage of the license’s total use count.

Possible values:
- count
- percentage
If empty, percentage is used.

ConsumptionConstraint

Define how many license seats a single user can consume.

This example rule allows one seat per user.

"ConsumptionConstraint":{"maxConsumptionCount":1}

Fields:

maxConsumptionCount

Define how many license seats a single user can consume.

Format: Positive integers