License Management

In Data Refinery Designer (DR Designer) or DR Designer API, a user can install a Data Refinery license. The purpose of the license is to regulate a client’s access for using the product. To install a license, a user must have the CONFIG_ADMIN permission which can be granted by users with the USER_ADMIN permission.

Kingland clients can sample Data Refinery in trial mode without a license. They can upgrade their product by inputting a new License Key in the DR Designer. This method offers a seamless upgrade for full access to Data Refinery. The following instructions will walk through installing, monitoring, and managing a Data Refinery License.

Table of contents

Trial Mode

The DR Designer offers a Trial Mode for users to sample Data Refinery without a license. The application may also enter Trial Mode if the installed license becomes invalid or expired. While in Trial Mode, some functionalities are limited:

  • SSO authentication is disabled
  • Resources are limited to 1 Project, 5 Sources, and 1 Background Task
    • For each resource type, if the amount is at the limit, then no new resources can be created.
    • For each resource type, if the amount is above the limit, then they become read-only.
    • Resources can still be deleted when at or above the limit.

Endpoints limited by Trial Mode:

Endpoint HTTP Method Affected By Resource Limit
/api/sources POST, PUT Yes
/api/sources GET No
/api/sources/:ID GET, DELETE No
/api/sources/:ID/versions POST No
/api/sources/:ID/upload POST No
/api/sources/:ID/versions/:VersionID/upload POST No
/api/sources/query POST No
/api/sources/:ID/crawler/start POST No
/api/projects POST, PUT Yes
/api/projects/:ID/associations POST Yes
/api/projects/:ID/associations DELETE No
/api/projects GET No
/api/projects/:ID DELETE No

How to Install a License in DR Designer

To reiterate, only a user with the CONFIG_ADMIN permission can install a license in DR Designer. To acquire the CONFIG_ADMIN permission, a USER_ADMIN must grant the permission to the user. For more information, refer to the Permissions and Roles page.

  1. Once logged in to DR Designer with the CONFIG_ADMIN permission, the top right corner of the screen will display a cog icon to the right of the user’s name. Click the icon.

    Setting Icon

  2. By clicking once, a box will appear below the cog and the username. Hovering the cursor over the box will underline the button “Manage Data Refinery License.” Click Manage Data Refinery License to continue.

    Manage License Button

    A new page will load displaying the License Management page. This page will display the status of the Data Refinery license currently in use.

  3. To update the license, a Kingland customer support lead should have provided the Customer ID and License Key to the assigned CONFIG_ADMIN. Type the Customer ID in the Customer ID field.

    License Management Page

    Note. The Customer ID will only contain numbers.

  4. Then, type or paste the License Key into the License Key box.

    Alternatively, the CONFIG_ADMIN has the choice of uploading the License Key as a file. A Kingland customer support lead may provide a License Key file directly to the CONFIG_ADMIN for upload. The only information in the file MUST be the License Key to install the license.

    Only one input method is allowed to enter the License Key.

  5. Select the Install License button when the fields have been completed.

    Install License Button

    Caution. Installing a new license will overwrite the existing Data Refinery license.

If the install process was successful, a green banner will appear at the top of the License Management page.

License Successful Banner

The DR Designer should refresh the license status at the top of the page to reflect that the license has been installed and pending validation. This license status should also reflect the expiration date of the Data Refinery license.

If the install process was unsuccessful, a red banner will appear at the top of the License Management page. No changes to Data Refinery would have been made.

License Failure Banner

Refer to the DR Designer API Documentation for more information on installing a license.

License Monitoring in DR Designer

The DR Designer offers a few ways for UI and API users to monitor the current Licensing status.

UI Status Messages

The License Management page will display the license status at the top of the page. This status indicates to the CONFIG_ADMIN the authorization of Data Refinery or if any potential action needs to be taken for authorization. Read the list of status messages below for explanations of each status.

  • Installed and Valid
    • Successful license installation, authorization approved.
  • Installed and Pending Validation
    • Successful license installation, but awaiting authorization.
  • Licensing Server Unreachable - $Days Remaining
    • Data Refinery cannot connect to the license server.
    • $Days is the number of days before entering Trial Mode.
  • Validation Failed
    • The License Key was entered incorrectly, or an old key was used.
  • Not Installed
    • The License Key or Customer ID was entered incorrectly.
  • Expired
    • The license needs to be updated to restore full access and authorization.
  • Expires Soon
    • The license needs to be updated before access becomes limited.

Regardless of the license status, the expiration of the current license will be displayed.

Application Behaviors

Depending on the license status, Data Refinery will behave differently for users. The following list explains the most common scenarios regarding Data Refinery licensing.

  • Without a license,
  • When a license has exceeded its expiration date,
    • Data Refinery will not enter Trial Mode immediately, but will notify users via UI and API that the current license is expired. Contact Kingland customer support to renew the license.
  • When a license can’t be validated,
    • After 14 days, Data Refinery will transition to Trial Mode.

Depending on the license status, the entitlements may change. The entitlements, or limit to the number of resources a customer can have in Data Refinery, is sent to the license server. For example, if Data Refinery transitions from Trial Mode to full operational status, the entitlements will most likely increase. The license server receives the following information,

  • Number of Projects
  • Number of Sources
  • Number of Users
  • Number of Tasks

Only the numbers of these resources are recorded and sent to the license server for tracking entitlements.

License Status API

For users of the DR Designer API, an endpoint GET /license/status is available to query for the current license status and resource limitations. This endpoint is available to all users, and provides the following information:

  • Trial: Whether DR Designer is in Trial Mode.
  • Status: The current licensing status.
  • IsLimited: Current resource limitation state, 0 indicates below limit, 1 indicates at limit, and 2 indicates above limit.

Example output:

{
  "Trial": false,
  "Status": "OK",
  "IsLimited": {
    "Project": 0,
    "Source": 1,
    "Task": 2
  }
}

Visit the API Documentation for more details.

How to Update a License in DR Designer

A Data Refinery license would need to be updated if the current license was a trial or a Kingland client renewed their subscription. A CONFIG_ADMIN user would have the correct permissions to make this change.

  1. After logging in to DR Designer, select the cog icon in the top right corner of the page. Click Manage Data Refinery License to continue.

    Manage License Button

  2. Type the Customer ID into the Customer ID field.

    License Management Page

  3. Then, type or paste the new License Key into the License Key box.

    Alternatively, upload a file containing the new License Key.

  4. Select the Install License button once the fields are complete.

    Install License Button

    Caution. Installing a new License Key will overwrite the existing Data Refinery license.

If the install process was successful, a green banner will appear at the top of the License Management page.

License Successful Banner

The DR Designer should refresh the license status at the top of the page to reflect that the new license has been installed and pending validation. This license status should also reflect the new expiration date of the Data Refinery license.

If the install process was unsuccessful, a red banner will appear at the top of the License Management page. No updates to Data Refinery would have been made.

License Failure Banner

Refer to the DR Designer API Documentation for more information on installing a license.

Copyright © 2025 Kingland Systems LLC