Introduction

When you want to access a Dashboard schema, a special license key is required. This license key grants specific access to one or multiple Dashboard schemas for the web application in which the license key is installed. There are two types of license key:

• current (introduced in January 2022)
• legacy

See below for more information about each.

Current license type

The current license key was introduced in January 2022:

This type of key restricts users as follows:

1. Purchased CAST data = INSIGHT (stands for Imaging and/or any of the 3 Dashboards: these are defined as P1=Imaging, P2=Health, P3=Engineering, P4=Security)
2. Named user for consumption = individual with a non-floating, unique and personal access rights to the purchased CAST data
3. Period = the duration of the purchased License - in all circumstances this is cannot exceed 1 year

Legacy license type

The legacy key is accepted in all Dashboards regardless of release:

This key restricts users via a token system in two ways:

1. A GLOBAL token is consumed for each named user authorized to access "All Applications" in all the target Dashboard schema(s) - for example an Architect
2. A UNIT token is consumed for each named user authorized to access a named Application in a specific Dashboard schema - for example a Project Leader

UI behaviour when using a legacy license key

All existing valid legacy license keys will function exactly as they are intended, however, if you are using one, users with the ADMIN role will now see a message explaining that a new license key type exists and that you should contact support to get more details. This message can be ignored for the time being, and all functionality will remain available:

Where do I obtain a license key from?

A license key can only be generated by CAST Support. Please open a new ticket and request a license key for your CAST Dashboards.

How do I install a new or edit an existing license key?

≥ 2.5 UI method

A specific license key UI is available. To access it browse to the following location - your login must have the ADMIN role:

http://<server>:8080/<dashboard>/authorisation/index.html

Or use the following option:

The interface is available in the License tab:

Enter your license key using the Edit option:

When a key is successfully entered, the UI will update to show the license key details:

Note that if you are updating/editing an existing license key, the list of users that have already logged in to the CAST Dashboards will be reset and will be repopulated as users log back in.

1.x and 2.0 - 2.4 - legacy license.key file method

• First create a new empty text file
• Rename the new text file license.key
• Now open the text file in a text editor and paste the license key that you have been sent into the first line.
• Save the license.key file.
• Now copy or move the license.key file to the following location:

WAR 1.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\license.key

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\license.key

ZIP ≥ 2.x
<unpacked_zip>\configurations\license.key

JAR ≥ 2.x
Windows: %PROGRAMDATA%\CAST\Dashboards\<dashboard>\license.key
Linux: /root/ProgramData/CAST/Dashboards/<dashboard>/license.key

Following any changes you make, restart your application server so that the changes are taken into account.

Using the RestAPI (any release)

Use the following URI in PUT mode:

http://<server>:<port>/rest/server/license

With the following .JSON payload:

{
	"key": "<license_key>"
}

How can I check whether a license key has been successfully installed?

To check whether a license key has been successfully installed in the web application, you can use the RestAPI interface. Open a browser and go to the following URL, ensuring that you modify it to conform to your environment:

WAR:
http://<server>:<port>/<dashboard>/static/default.html

JAR/ZIP:
http://<server>:<port>/static/default.html

Login (using the Basic Authentication field with any user (it does not have to be a user that has the ADMIN role)). Now enter "server" in the URI field and click Submit:

The result will be shown in the Response (Pre-view) tab. In this example, you can see that a restricted license key has been installed:

Note that the following statuses may be returned:

What happens if I attempt to access data when no license key is present?

If a user attempts to login to the dashboard when no license key has been configured, the following message will be displayed:

Current license key tips

Use of license.xml file not required (current license key type only) for data authorization

The current license key type has no concept of RESTRICTED vs UNRESTRICTED unlike a legacy type license key (note that the RestAPI will always report a current license key as "RESTRICTED" however). This means that if you are using a current license key type, there is no need to define data authorization using the license.xml file as is the case with a legacy license key type (explained in the section below). All data authorization can be managed via the built in UI as described in Data authorization - 2.x and above.

What happens if more users than I am licensed for log in (current license key type only)?

When using a current license key, the number of users that are authorized to use the CAST Dashboards is always specified in the key:

This is also shown in the UI:

The UI provides a list of users that have logged in to the Dashboard/RestAPI - each entry will consume 1 user license. In the example below, 4 users have logged in and the count of "Associated Users" reflects this:

In the example above, the number of users that have logged in to the Dashboard/RestAPI exceeds the number of authorized users (as defined in the license key) and in this situation a message will be displayed on every page in the dashboard as follows:

Click to enlarge

There are too many authorized users to connect to your Dashboard. To avoid this limitation, you can contact your CAST Administrator to update your licensing terms & conditions.

If you receive the message described above, deleting users from the list of logged in users so that you conform to your licensing agreement will ensure that the message is removed:

Legacy license key tips

How to authorize users when using a RESTRICTED license key (legacy key type only)

If you have installed a restricted license key (i.e. a key that specifies GLOBAL/UNIT tokens (legacy license key)), you can authorize named users to access either ALL the applications in all the target Dashboard schemas, or you can authorize named users to access a named Application in a specific Dashboard schema.

This authorization is achieved using the following XML file, which you can edit in a text editor - see Data authorization - 2.x and above and Data authorization - 1.x for more information:

WAR 1.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\license.xml

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\license.xml

ZIP ≥ 2.x
<unpacked_zip>\configurations\license.xml

JAR ≥ 2.x
Windows: %PROGRAMDATA%\CAST\Dashboards\<dashboard>\license.xml
Linux: /root/ProgramData/CAST/Dashboards/<dashboard>/license.xml

Authorization is achieved by adding a line into the file. Each line you add to file will use up ONE single user (or GLOBAL or UNIT token.

Authorize a named user to access ALL Applications in ALL the target Dashboard schemas

Add the following line under the commented text to grant the user "James" access to ALL applications. Doing so will use ONE single GLOBAL token:

<!-- Each following line will consume a global access token -->
<authorization user="James" allApplications="true"/>

Following any changes you make, save the license.xml file and restart your application server so that the changes are taken into account.

Authorize a named user to access a named Application in a target Dashboard schema

Add the following line under the commented text to grant the user "John" access to the "MEUDON" Application stored in the "V83_CENTRAL" Dashboard schema. Doing so will use ONE single UNIT token:

<!--Each following line will consume a unit access token -->
<authorization user="John" application="MEUDON" adgDatabase="V83_CENTRAL"/>   

Following any changes you make, save the license.xml file and restart your application server so that the changes are taken into account.

What happens with a RESTRICTED license key (legacy type only) if I authorize more users than I am licensed for?

The situation listed below will cause you to be in breach of your license:

1. You are using a RESTRICTED license key (i.e. a key that specifies the number of GLOBAL/UNIT tokens)
2. You are limited to 2 GLOBAL tokens (2 users with ALL Application authorization) and 5 UNIT tokens (5 users with named Application authorization) on your license key
3. You authorize (via the license.xml file) either:
   1. 3 users to access ALL Applications
   2. 6 users to access a named Application

As such, a message will be displayed on every page in the dashboard as follows:

≥ 2.x
There are too many authorized users to connect to your Dashboard. To avoid this limitation, you can contact your CAST Administrator to update your licensing terms & conditions.

1.x
THIS SOFTWARE IS SUBJECT TO A LIMITED ACCESS.
There are too many authorized users to connect to your Dashboard.
To avoid this limitation, you can contact your CAST Project Manager to update your licensing terms & conditions.

If you receive the message described above, you have two options:

1. Review and reconfigure the users that have been authorized to access data in the Dashboard schema using the license.xml file - i.e. decrease the number of users that have been granted access.
2. Contact the CAST Consultant responsible for your project, or contact your Account Manager to request an update to your license.