The Telerik Platform product is retired.Learn more

Setting Up Data Link Server on Windows

Setting Up Data Link Server on Windows

Before you can use Data Connectors you must have a running instance of the Data Link Server. The Data Link Server is a Java web application, hosted on an embedded Apache Tomcat HTTP server that relays and translates any requests made to your Telerik Platform app to your relational database.

This article explains the installation steps of a Data Link Server on a Microsoft Windows machine. In order to install it on a machine running Linux, follow the instructions in Setting Up Data Link Server on Linux.

This article is organized as follows:


Before starting the Data Link Server installation make sure you have the following:

  • A machine running Microsoft Windows that has network connectivity to the database server. This machine will host the Data Link Server.
  • Java SE Runtime Environment (JRE) or Java SE Development Kit (JDK) version 8 or later installed.
  • An environment variable named JAVA_HOME set to the path where the JDK (or the JRE) is installed. (For instance: C:\Program Files\Java\jdk1.8.0_05). Detailed instructions can be found in the Oracle documentation

Acquiring the Installation Package

  1. Navigate to the Downloads page.
  2. Under Select platform or tool, select Data Link Server.
  3. Click the Download button and save the ZIP file to your hard drive.
  4. Extract the files to a suitable location on your hard drive.

You can run the server application once or install it as a system service for continuous running.

For the following instructions, you need to be executing all commands from the command prompt as an administrator.

When the server is starting it reads the configuration file). Always check if it is set up correctly otherwise the server uses default values. You can learn how and when to set some of the more important options in the remaining sections of this article. Keep in mind that configuration updates take effect after restarting the Data Link Server.

Running from the Command Prompt

The Data Link Server comes with a batch script that can be used to run the server without installing it.

To run the Data Link Server once, open a command prompt window and go to the bin directory inside the folder where you extracted the Data Link Server package, then run the following command:

C:\<path to Data Link Server folder>\bin> DataLinkServer.bat

Running as a Windows Service

Running the server from the command prompt is not the best solution if you need it always running. A better alternative is to install it as a Windows service so it is started automatically when the machine boots.

To install the service, open a command prompt window and go to the bin directory inside the folder where you have extracted the Data Link Server ZIP package, then run this command:

C:\<path to Data Link Server folder>\bin> installWinService.bat

Setting up the Maximum Heap Size

By default the Data Link Server is set up with a Maximum Heap Size (MHS) of 256 MB. Setting up a higher value may increase the performance because more objects may be kept in the heap and the garbage collection will occur on greater intervals. This is especially useful when you have to regularly fetch large data sets. The recommended value for the MHS may be application-specific. Set the MHS to a value that is no larger than the physical RAM available on the machine.

Supply the following parameter when running the application to specify the MHS in megabytes:

C:\<path to Data Link Server folder>\bin> installWinService.bat --JvmMx=2048

Testing the Server

The easiest way to check if the Data Link Server is running is to open its URL (http://machine-name.domain:port) in a web browser. For example, if you are testing from the machine where the server is installed and it runs on the default port, the URL would be http://localhost:9090. The expected response is HTTP status code 200 and a simple JSON-formatted message:

    "Result": "OK"

Setting Up Authentication

The security is not complete without configuring the server-to-server authentication between Telerik Platform and your instance of the Data Link Server. The integrated authentication mechanism restricts the access to your Data Link Server, allowing in only a Telerik Platform app authenticated with an appointed key known to both parties. The secret key is automatically generated for each Telerik Platform app.

Take these steps to set up authentication:

  1. Download the key from the Create a Data Connector/Edit page. You can access the page in your Telerik Platform app on Data > Data Connectors > Create a Data Connector/Edit > Download Authentication Key.

    Alternatively, you can use the RESTful API to download the authentication key.

    The file name of your download will be the Telerik Platform App ID followed by the .txt file extension (for example 3YVPn8Al5Vi8Yfe4.txt). The content of the file is a JSON Web Token, the secret key used by Telerik Platform and the Data Link Server to sign and validate requests.

  2. Copy the downloaded file to the keys subfolder of the Data Link Server installation folder.

  3. Open the configuration file and ensure that the security.token.enabled is uncommented and set to true.

If for some reason you believe that your secret key has been compromised, you can regenerate it as discussed in Managing the Authentication Key Using the RESTful API.

Enabling SSL

By default, the Data Link Server works over HTTP. It is strongly recommended that you configure an SSL certificate so that Telerik Platform can communicate with the Data Link Server over HTTPS.

Take these steps to enable SSL:

  1. Acquire an SSL certificate.

    The supported format is the Java KeyStore (JKS) format, the standard Java format. You can generate a JKS using the keytool command-line utility. The same tool is also used for importing existing certificates into the keystore. For complete instructions see the official Apache Tomcat documentation.

  2. After you have acquired the keystore file containing the certificates, configure the ssl.* set of configuration options.

Updating the Server

In the steps below you will learn how to update the Data Link Server to the latest version while preserving the configuration.

  1. Follow the steps for uninstalling the system service (in case you are running the server as a system service) or stop the running instance of the Data Link Server from the console window.
  2. Backup the following files from the current installation folder of the Data Link Server.
    • data-connectors.config—stores the database tables to content types mappings
    • file (if available)—stores the Data Link Server configuration
    • Java KeyStore (JKS) file (.keystore) (if available)—stores the SSL encryption key/certificate
    • keys/<security-key-file.txt> (if available)—stores the server-to-server authentication token
  3. Remove the current installation folder.
  4. Acquire and extract the installation package as explained in Acquiring the Installation Package.
  5. Copy the data-connectors.config configuration file from your backup folder to the new Data Link Server folder.
  6. Examine and configure (if needed) the file.
  7. Optionally, restore your Java KeyStore (JKS) file (.keystore) and keys/<security-key-file.txt> file from the backup to their respective locations in the new Data Link Server folder.
  8. Run the server application.

Uninstalling the Microsoft Windows Service

You can run an uninstallation script to remove the service. It is located in the same bin folder as the installation script. You can double-click it in Windows Explorer or run it from the command prompt:

C:\<path to Data Link Server folder>\bin> uninstallWinService.bat

Next Steps

You are now ready to create your Data Connector in Telerik Platform. You can learn how in Creating an SQL Data Connector Using the Portal and Managing Content Types Using the Administration API.

See Also

Contact us: +1-888-365-2779
Copyright © 2016-2018, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.