All About Windward Studios Licensing
This article covers license keys for the various Windward Studios products; common licensing software errors; licensing restrictions; license key corruption issues; and other licensing tips.
Please use these links to jump to your section of interest.
How Do I Retrieve My License Keys?
If you have not yet purchased keys or need to upgrade them, please email email@example.com.
- Point your browser to https://store.windward.net.
- Click on 'Login'
- Enter your login info. If you've forgotten your information you can request it via this screen.
- Copy your keys from your browser then paste them to the appropriate place for your product (see How Do I Update My License Keys? below).
Keys are listed in two sections: version 9.x and higher and version 8.x and lower.
When Must I Update My License Keys?
When you purchase a maintenance agreement in conjunction with your Windward Studios product license, you are entitled to install all Support Releases for your version and earlier versions of the software, as long as your maintenance contract is current.
As a general rule, the license key you are assigned will work with the current version of a Windward Studios product; will also work for previous versions; but will not work for subsequent releases. However, if your maintenance contract is up to date, you simply retrieve a new license from the Windward store (see How Do I Retrieve My License Keys?).
If you have upgraded any of your Windward Studios products (a Report Designer or a Report Engine), you may receive a license error similar to this:
"This license is only valid up to version 15.*.*"
If you see this error, your keys are only valid up to the version current at the time you downloaded them (in this case version 15). To fix this, login to the Windward Store and retrieve your current license keys.
When we make any changes to your current keys, such as changing the length or date of your maintenance contract; adding new products; or changing license restrictions (e.g. extending a Report Engine license from two to four cores); you must go to the Store to download your updated keys.
How Do I Update My License Keys?
How to update your license keys varies depends upon the Windward Studios product you're licensing.
Licensing for Report Designer Office Edition
For the Report Designer, to see the key you have installed, open MS Word, Excel, or PowerPoint. In the ribbon, click the AutoTag Manager tab and click the License button. (You may see a prompt asking if you want to allow the program to make changes to your device - just click 'OK'.) A window will appear with your license key.
Licensing for .NET Report Engine
The license key must be visible to the Report Engine when it starts. Your Report Engine license key should be entered into
- the <app>.exe.config file (where <app> is the name of your embedding application)
- the Web.config file of your embedding ASP.NET application
You cannot use WindwardReports.dll.config. And the config file must be in the correct directory - the same as where the <app>.exe file is for applications and in the IIS website root directory for Web.config.
Licensing for Java Report Engine
The key must be visible to the Report Engine when it starts. The Report Engine will look in the Java application properties for your application for the property ('license') with the license value. By default this is in the WindwardReports.properties file. However, you can use any appropriate means to insert the license key into your application's Java application properties.
Licensing for Report Engine for RESTful
The license key must be visible to the Report Engine when it starts. Your Report Engine license key should be entered into the Web.config file in your Report Engine IIS website's home directory.
Important License Information
- You must have a separate license for each system where a Windward Studios product is installed and executed.
- You don't need a client license for machines running a browser used to view generated output, only for the machine the output was generated.
- One license per machine is required.
- You must purchase support and upgrades for either all licenses or none.
- The "Standard Server" license runs an unlimited number of reports daily. A single license for a server allows it to be run on one machine only. It is not a license to install the product on an unlimited number of machines.
- Where the WindwardReports.jar or WindwardReports.dll file is located is irrelevant— a license is needed for each machine where a Windward Studios product is installed and executed.
- You do not need a separate license for a cold backup system as long as the cold backup system has the same IP address as the hot server.
- Your Report Engine version should always be equal to or newer than the version of the Report Designer you're using. This is because newer versions of Report Designer may use newer features that older versions of the Report Engine don't recognize.
License Key Tips
Here are some tips on using Windward Studios licenses:
- When changing a key in a Report Engine, you must restart the application or service embedding that Report Engine for the new license key to take effect.
- In the Java Report Engine's WindwardReports.properties file, you can enter a multi-line key but you need a "\" (backslash) at the end of every line except the last line.
- In the .NET Report Engine's <app>.exe.config file, ensure the entire key is in double quotes, e.g. "BDjfsrtf".
License Key Exceptions
If a restriction of a license key (e.g. number of machines, number of cores, number of threads, etc.) is exceeded you will see these license key exceptions.
If your Report Designer is given a license key for another Windward Studios product, this pop up will appear:
If your Reporting Engine is given a license key for another Windward Studios product, you will see an exception similar to this:
* Exception occurred: Your license is for a different Windward product 1
Error: Your license is for a different Windward product 1
Too Many Machines
If your Reporting Engine is running on more than the licensed number of machines, you will see an exception similar to this:
net.windward.util.LicenseException: Running on more machines than licensed for. This server:xxx.xxx.xxx.xxx; Running: 2, Licensed: 1 Addr: yyy.yyy.yyy.yyy (hostname1, hostname2)
Too Many Threads
If your Reporting Engine is being executed by more than the licensed number of threads simultaneously, you will see an exception similar to this:
net.windward.util.LicenseException: Running on more threads than licensed for. License good for maximum of 2 threads
Too Many Cores
If your Reporting Engine is running on a machine with more than the licensed number of cores, you will see an exception similar to this:
net.windward.util.LicenseException: License violation License violation - licensed for 4 cores (across all CPUs), this computer has 8 cores.
Developer License Exceptions
Developer licenses allow one thread at a time and a maximum of 250 reports a day. If the thread limit is exceeded you will see an exception similar to this:
License Error: Only allowed 1 request at a time using this server
If the 250-report-a-day limit is exceeded, you will see an exception similar to this:
* only 250 reports a day in development & limited version servers *
WARN (?:?) - only 250 reports a day in development & limited version servers.
WARN (?:?) - Error processing request from /xxx.xxx.xxx.xxx:yyy
net.windward.util.LicenseException: Surpassed the limited server daily limit
License Key Corruption
If you see a license exception similar to Invalid license key (BAD_XML), your license key may have become corrupted while forwarding it in email.
If someone who received an HTML email from Windward Studios with the proper license key then forwards that key as a plain text email to another recipient, the email system may corrupt the uuencoded license key string in the original HTML email. Because of this, it is recommended to retrieve your keys from the Windward Store as described above. But if license keys must be forwarded via email, save the keys from the Windward Studios email to a text file, then forward the text file as an email attachment. (Windward Studios doesn't initially deliver keys using this method because the email may be blocked by a firewall.)
Internal Communication Protocols and Ports
The Windward Studios licensing mechanism communicates using both TCP and UDP network protocols on the ICANN-registered port 1707.
During the Report.Init() process the license key file is read and the following license key properties are broadcast:
- license key number
- total number of machines on which the key is valid to run
- total number of threads or cores per machine for which the license key is valid
A running total is kept of the following values, each of which are updated when a broadcast is received on a system where a Windward Studios product is running:
- current total number of machines on which the license key is used
- current number of threads or cores allocated for the reporting process on each machine where the license key is used
For additional details about how these requests operate refer to the License Copy Protection section below.
Report Engines licensed with a Developer or Test license will print one of the following watermarks at the bottom of the last page of output:
To prevent license abuse, test and development keys generate password-protected (read-only) output, where the password is not made public. This applies to output types DOCX, PPTX, XLSX and PDF.
Restricted by Computer Host Name or IP Address
Some licenses are restricted to running on specific computers by IP address and/or host name. If a license key has this restriction and is running on a computer that does not match the allowed systems, it will throw a license exception and list the disallowed IP address(es).
Restricted by Number of Calling Threads
Some licenses are restricted by the number of threads that can call a Report Engine simultaneously. If this license restriction is in effect, the licensing mechanism increments a counter each time a report is started (by calling ProcessReport.setupProcess) and decremented each time it completes (by calling ProcessReport.completeProcess() or ProcessReport.close()).
License keys also have the maximum number of cores restriction. If the system running a Windward Studio product has the same or fewer cores than the core limit in the license, then the number of threads limit is ignored. The number of threads limit only takes effect on systems that have more cores than the core limit in the license.
For example, if you have a license key for four cores and four threads, and the Report Engine is running on an eight-core machine, as long as no more than four threads call the Report Engine simultaneously, there is no license violation. But if a fifth thread calls the Report Engine while four threads that called the Report Engine are running, the fifth thread will fail with a license exception.
Windward Studios products themselves are single threaded. The thread count referred to in license keys is the number of threads that call a Report Engine simultaneously to generate output. This thread limit is counted across all virtual machines (VM), Java Virtual Machines (JVM), and .NET Common Language Runtimes (CLRs) on a physical server. If you have two VMs, one with three JVMs and the other with four CLRs, and all are running applications embedding Report Engines, all seven environments count against the total. If those environments each have four threads generating output, the total is 28 threads. But the total is 28 only if all 28 threads are generating output at the same time. If the Report Engines all generate output at different times (yes, unlikely – even with semaphores), then you only need a license that allows one thread.
Because the count is not decremented until a Report Engine's output is completed, if output is interrupted by an exception, or you decide to not complete it, you must call ProcessReport.close() to decrement the count. Otherwise that thread remains counted. If you abort a JVM while output is being generated, all other JVMs will retain the count for all Report Engines generating output.
License Copy Protection
This section contains detailed information about running Windward Studios products on multiple workstations or servers. It is provided to help the system administrator and third-party developers understand how Windward Studios licensing works.
All editions of the Report Designer and Report Engines have a copy protection mechanism that checks for license violations. The licensing mechanism in each product works the same but are independent of each other. In other words, the Report Designer checks for Report Designer license violations, but does not check Report Engine license violations. The Java Report Engine checks Java Report Engine license violations but does not check for .NET Report Engine, etc.
In each case, when the product starts, it asks all other systems running using the same license to identify themselves. Each system that is already running will respond to that request, identifying itself.
A license specifies the number of machines for which the license is valid. If that number of machines responds to the Report Engine that just started, then the license is in full use and the Report Engine just starting will fail with a license exception and not generate output. A license exception will not be thrown by any of the existing running Report Engines.
The Report Designer starts when Office (Word, Excel or PowerPoint) starts. It ends when all copies of Office on a user’s workstation exit.
A Report Engine starts when ProcessReport.init() is called or the first time output is generated. It ends when the JVM or CLR which called it exits. So if ProcessReport.init() is called and no output is generated for two weeks, but the VM is still running, that system is still using the license and will be counted against that license. If ProcessReport.Init() is not called and the first output is generated two weeks after the Report Engine starts, that is when the Report Engine will determine if it complies with its license restrictions for its server.
One license is good for a single VM running under a single set of credentials. If you have two VMs on a single physical machine, they require two licenses. If on a single VM you run two applications embedding a Report Engine under two sets of credentials, they require two licenses.
The licensing mechanism is designed so licenses can move between machines. Keep in mind that if you want to stop using a license on a specific server, you must stop all VMs on that server that called a Report Engine.
Each license has a unique ID. Two systems have the same license if and only if they have the same ID and the same restrictions such as product, number of reports, etc. If you purchased three server licenses, and then later two server licenses, you probably have two different licenses and each will have a different ID and will only check for use of itself. In this case, if you would prefer a single license good for five servers (or any number of valid licenses), contact us and we can swap those licenses for a single license good for your five servers.
If a Report Engine running within a VM fails with a license exception, it will continue to do so on subsequent calls even if other Report Engines have decremented the machine count by exiting. The VM must be restarted for the Report Engine running within it to try again.
The license exception is a runtime exception and therefore does not require there be try/catch blocks for it. This decision was made because a license exception will only be thrown when the Report Engine starts, and if there is a license problem, it will always be thrown. There are a large number of methods that can throw this exception, so it would have required additional try/catch blocks around almost all calls to Report Engine APIs. While your program does not require try/catch blocks for license exceptions, you may implement them if you wish.
The class net.windward.tools.ListServers (in the Java Report Engine Utilities jar) will list all machines running the Report Engine by IP address. In the Report Designer the About box lists the IP addresses of all machines running Report Designer. The utility finds all systems regardless of license ID and settings and only reports IP address and host name.