Enabling Automated Volume Counting in iText 5 with JSON Licenses

Overview

Starting with iText 5.5.13.5, iText 5 supports the Unified Licensing Mechanism with JSON license files and integrated volume counting and automated usage reporting. This brings iText 5 in line with the iText 7.2+ event-based volume system.

This is a complete installation guide for enabling automated volume counting in iText 5, followed by FAQs explaining how counting works, what data is sent, and how to troubleshoot and customize behavior.

Installation Guide: Enable Volume Counting in iText 5

Important

If your license key file is a JSON file, you can enable automated volume counting and remote reporting in iText 5.5.13.5 and newer.

Unified JSON licenses require licensing.base 4.2.5+.
iText 5 continues to accept old XML licenses (via licensekey 1.x–3.x), but XML does not provide automated volume counting.
Java 8+ is required to use the unified mechanism in iText 5. Without unified licensing, iText 5 remains compatible with Java 5+.

If both XML and JSON licenses are loaded, the JSON license is used while it remains valid. If it expires during runtime, an exception is thrown. If suppressed, the old XML license continues to work (without automated counting).

Requirements

iText 5.5.13.5 or newer (latest version is recommended)
licensing-base 4.2.5 or newer (latest version is recommended)
licensing-remote (volume reporting plugin) 4.2.5 or newer (latest version is recommended)
Java 8+ (for unified licensing in iText 5)
Valid JSON license key file with volume limits
Network egress on port 443 to iText volume endpoints (see Troubleshooting)

Add Dependencies

Java (Maven)

XML

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

<dependencies>
  <dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itextpdf</artifactId>
    <version>${itext.five.version}</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>

Transitive dependencies:

AWS SDK for Java 1.11.x (bundled dependencies)
slf4j 1.7.13+ (configure logging for com.itextpdf)

Manual download links (if not using a build tool):

.NET (NuGet)

Search for itext.licensing.base and itext.licensing.remote in NuGet Package Manager, or use the following links:
- itext.licensing.base
- itext.licensing.remote
Alternatively, you can manually download them from our hosted repository and install the required transitive dependencies:
- licensing-base binaries
- licensing-remote binaries
Then install the required transitive dependencies: AWSSDK.Kinesis/AWSSDK.CognitoIdentity 3.7.x and their dependencies
- AWS SDK for .NET

.NET only: licensing-remote 4.2 depends on AWSSDK.CognitoIdentity 3.7.x. If your project references AWS SDK 4.x, NuGet may resolve incompatible assemblies as AWS SDK 4.x contains breaking changes in the API. For more information see Resolving MissingMethodException and AWS SDK Compatibility in .NET Applications.

Load the JSON License

Load the license file as early as possible in your application. Loading sets up volume counting and remote reporting automatically. A loaded license is active for the entire CLR/JVM runtime; provide a separate copy per CLR/JVM if needed.

Java

import com.itextpdf.licensing.base.LicenseKey;
import java.io.File;

public class App {
  public static void main(String[] args) {
    LicenseKey.loadLicenseFile(new File("path/to/itextkey.json"));
    // proceed with iText 5 usage
  }
}

.NET

using System.IO;
using iText.Licensing.Base;

class Program {
  static void Main(string[] args) {
    LicenseKey.LoadLicenseFile(new FileInfo(@"path\to\itextkey.json"));
    // proceed with iText 5 usage
  }
}

Network Requirements

For remote reporting, ensure outbound HTTPS (443) access to:

Requests are outbound-only; no inbound connectivity is required.

Troubleshooting

With logging enabled for the iText namespace (Java: “com.itextpdf"; .NET: “iText"), look for messages like:

The 'licensing-remote' 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.

Meaning: the remote volume library failed to initialize. Verify dependency versions and use Maven/Gradle/NuGet to avoid transitive dependency issues.

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.

Meaning: data could not be sent to the server. Check outbound access to the endpoints listed above. Proxy environment variables are honored for volume reporting.

FAQs: iText 5 Volume Counter

How do I enable volume counting in iText 5?

Load a valid JSON license file using licensing-base 4.2.5+ and include licensing-remote. No extra code is required; the system automatically emits events and statistics.

Can I use my existing XML volume license with iText 5?

Automated volume counting requires JSON licenses in iText 5. XML licenses work for licensed mode but do not enable automated reporting.

If you must log usage with XML, implement a Counter and register it via CounterFactory. See “How can I log the number of documents/bytes I’ve processed?” for a full example.

Are JSON license files compatible with versions earlier than iText 5.5.13.5?

No, JSON license and automated volume counting requires iText 5.5.13.5 or newer.

What data does iText 5 collect?

We collect information about the version of iText and its executable environment, the license key, the event type (which product) and the time it occurred.

If you want to know more details about the information that we collect, refer to your Software License Agreement (SLA).

How are events counted in iText 5?

Reading or stamping a PDF: an event is reported at the end of opening (read or stamping modes)
Creating a PDF: the event is reported at document close
Events are batched and sent periodically to the remote service

Is volume counting safe in closed environments?

Yes, if you allow outbound HTTPS to the listed endpoints. If connectivity drops, events are cached in-memory during the current runtime and retried on the next batch. Caches are not persisted across process restarts.

Can I run a custom counter alongside automated counting?

Yes. You can still register a custom Counter (for local metrics, logging, or audits) while using the automated mechanism for official usage reporting.

Which Java versions are supported for unified licensing in iText 5?

Java 8+ is required. If you must use earlier Java versions (5–7), the unified mechanism is not available; iText 5 itself remains compatible with Java 5+ when unified licensing is not used.

Can I query remaining volume in iText 5 like in iText 7.2+?

Yes, you can check the remaining volume usage for iText 5 in the same way as for iText 7.2 and newer. See How do I query my current volume usage? for an example.