Volume Counter installation guide

Important!

As of the release of iText 7.2, the old licensing system was replaced by a new Unified Licensing Mechanism, which allows users to more easily check their usage and extended the event counting capabilities. This replaces the old itext-licensekey and itext-licensekey-volume dependencies with the new licensing-base and licensing-remote dependencies, and the version number for the licensing libraries was increased from version 3.x to 4.x. In addition, it replaces the old XML license file with a new one in JSON format.

Simply put, if your license key file is an XML file you should follow the instructions marked iText 7.1.x in this installation guide. However, if you have a JSON license key file, see the instructions for iText 7.2.x and newer.

With the introduction of version 3.0.0 of the license key library, we also released a volume based counting mechanism based on an event system. iText and its add-ons will send events through this event system. When a volume license key file is loaded, the statistics concerning usage will be sent to iText servers. This means that the machine where you run your application needs an active Internet connection.

As of version 3.0.6 of the iText License Key and License Key Volume libraries we require that the License Key Volume library be loaded for Volume customers. Proxy environment variables will be honored for Volume reporting.

NOTE: If your license expires during runtime, it will revert to AGPL mode.

In iText 7.1.11 we introduced version 3.1 of the License Key and iText License Key Volume libraries which required "Volume Subscription" license holders to specify if they want to do volume counting locally, or remote (our most convenient way for usage reporting).

You can check our Volume Counter FAQs for further details.

This guide will show you how to enable the automated monitoring of volume licenses (a.k.a a Capacity Rental License).

Requirements

You can refer to the Compatibility Matrix for the licensing-base and licensing-remote dependencies compatible with your version of iText Core. Note that if you are using iText 7.1.x, you need the itext-licensekey and itext-licensekey-volume dependencies.

The default remote reporting also requires the AWS SDK and its transitive dependencies; for more details see the following section.

Configuration of your project

To enable the volume monitoring as required by volume licensing, you'll need to set up your project to include the license key libraries and their transitive dependencies. For volume counting, you'll need the following: the license key core library, the license key volume library, and the transitive dependencies. Please make sure that you're always using the latest versions of these dependencies.

You'll need to download two license key dependencies:

For iText 7.2.x and newer

licensing-base: This is the license key core library.
licensing-remote: This is the plugin built on top of the license key core library to manage volume licenses.
Transitive dependencies: AWS SDK and its third-party dependencies and logging dependency.

For iText 7.1.x

itext-licensekey: This is the license key core library.
itext-licensekey-volume: This is the plugin built on top of the license key core library to manage volume licenses.
Transitive dependencies: AWS SDK and its third-party dependencies and logging dependency.

Java

To use the license key libraries in Java we advise you to use Maven or Gradle. This way you don't have to deal with transitive dependencies.

Alternatively, you can download the binaries manually and add them to your classpath.

Using Maven

To add the volume license key library to your Maven project, you'll need to add our repository to your pom.xml followed by the dependencies:

XML

<repositories>
    <repository>
        <id>itext-releases</id>
        <name>iText Repository-releases</name>
        <url>https://repo.itextsupport.com/releases</url>
    </repository>
</repositories>

For iText 7.2.x and newer

XML

<dependencies>
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext7-core</artifactId>
        <version>$release-core-7-variable</version>
    </dependency>
    
    <dependency>
        <groupId>com.itextpdf.licensing</groupId>
        <artifactId>licensing-base</artifactId>
        <version>$release-license-base-variable</version>
    </dependency>
    
    <dependency>
        <groupId>com.itextpdf.licensing</groupId>
        <artifactId>licensing-remote</artifactId>
        <version>$release-license-remote-variable</version>
    </dependency>
</dependencies>

For iText 7.1.x

XML

<dependencies>
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext7-core</artifactId>
        <version>7.1.17</version>
    </dependency>
    
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext-licensekey</artifactId>
        <version>$release-license-variable</version>
    </dependency>
    
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext-licensekey-volume</artifactId>
        <version>$release-license-volume-variable</version>
    </dependency>
</dependencies>

If you want to download and manage the binaries yourself

You can download the license key library binaries from our hosted repository here:

For iText 7.2.x and newer

For iText 7.1.x

The AWS SDK (1.11) can be downloaded from the following link. The distribution also includes the necessary third-party dependencies:

https://aws.amazon.com/sdk-for-java/

slf4j (1.7.13+) logging dependency. It can be downloaded from here:

https://www.slf4j.org/download.html

.NET

To use the license key libraries in .NET we advise you to use NuGet. This is the recommended way since you don't have to deal with transitive dependencies.

Alternatively, you can also download the binaries manually and add them to your project.

Using NuGet

For iText 7.2.x and newer

To add the libraries to your project, please find them through the NuGet Package Manager. Searching for the term "itext.licensing" will bring up the two dependencies in the search results.

For iText 7.1.x

To add the libraries to your project, please find them through the NuGet Package Manager. Searching for the term "itext.licensekey" will bring up the two dependencies in the search results.

If you want to download and manage the binaries yourself

You can download the binaries from our hosted repository here:

For iText 7.2.x and newer

For iText 7.1.x

The .dll can be found inside the .nupkg files. You can extract a .nupkg file in the same way as a .zip file.

Transitive dependencies

Installation instructions for transitive dependencies can be found here:

AWS SDK (specifically the AWSSDK.Kinesis package and its dependencies):

https://aws.amazon.com/sdk-for-net/

Common.Logging (only required for iText 7.1.x):

https://net-commons.github.io/common-logging

Loading the license file

NOTE: Loading the license file should be done as early as possible in the flow of your application using the static method of the LicenseKey class. When you load a volume license key, the license key library will set up everything for you—there is no need to set up any additional counter or logger. Also, once a license key has been loaded it is active for the entire CLR/JVM runtime, if you have multiple CLRs or JVMs accessing the same license key you should provide a copy of the license key for each CLR/JVM.

To load the license key file, you'll need to call the following lines of code:

For iText 7.2.x and newer

In the following examples, the license key file has been renamed to "itextkey.json" for convenience.

Java

JAVA

LicenseKey.loadLicenseFile(new File("path/to/itextkey.json"));

.NET

C#

LicenseKey.LoadLicenseFile(new FileInfo("@path/to/itextkey.json"));

For iText 7.1.x

In the following examples, the license key file has been renamed to "itextkey.xml" for convenience.

Java

JAVA

LicenseKey.loadLicenseFile("path/to/itextkey.xml");

.NET

C#

LicenseKey.LoadLicenseFile("path/to/itextkey.xml");

Troubleshooting

If a logging dependency is configured (for configuration instructions please refer to the respective logging dependency documentation) to include the iText namespace ("com.itextpdf" for Java and "iText" for .NET) then you can check for the following logging messages:

The 'itext-licensekey-volume' library is required for your license type, but it is missing or outdated. Please add or update this library. If you keep seeing this warning message, contact our support team: https://itextpdf.com/support.

This means the volume library has failed to initialize, please make sure that all transitive dependencies are available if you installed the dependencies via the binaries. Alternatively, use the recommended Maven/Gradle/NuGet method instead.

iText was unable to record your usage information as required by the Capacity Rental License. Please make sure this machine is able to connect to the iText Volume Server. If you keep seeing this warning message, contact our support team: https://itextpdf.com/support.

This means the volume library has failed to send data to our server. Please make sure that the following hosts are reachable from your environment:

For iText 7.2.x and newer

kinesis.eu-central-1.amazonaws.com:443
cognito-identity.eu-central-1.amazonaws.com:443
sdk-requests.licensing.itextpdf.com:443
sdk-login.licensing.itextpdf.com:443
sdk-health.licensing.itextpdf.com:443

For iText 7.1.x

kinesis.us-east-1.amazonaws.com:443
sdk-requests.licensing.itextpdf.com:443
sdk-login.licensing.itextpdf.com:443
sdk-health.licensing.itextpdf.com:443

More information

If you need further information about the volume counting in iText, such as how events are calculated and other details, see the Volume Counter FAQs.

[data-colorid=u03w2j4hdl]{color:#515151} html[data-color-mode=dark] [data-colorid=u03w2j4hdl]{color:#aeaeae}[data-colorid=qbm3brv42m]{color:#515151} html[data-color-mode=dark] [data-colorid=qbm3brv42m]{color:#aeaeae}Important!

Requirements

Configuration of your project

For iText 7.2.x and newer

For iText 7.1.x

Java

Using Maven

For iText 7.2.x and newer

For iText 7.1.x

If you want to download and manage the binaries yourself

For iText 7.2.x and newer

For iText 7.1.x

.NET

Using NuGet

For iText 7.2.x and newer

For iText 7.1.x

If you want to download and manage the binaries yourself

For iText 7.2.x and newer

For iText 7.1.x

Transitive dependencies

Loading the license file

For iText 7.2.x and newer

Java

.NET

For iText 7.1.x

Java

.NET

Troubleshooting

For iText 7.2.x and newer

For iText 7.1.x

More information

Important!