Managing premium connectors

Overview

Some Etlworks connectors — most Connected Apps, such as Salesforce, Marketo, Elasticsearch, Zoho, SharePoint, plus some NoSQL databases are premium connectors. Each one runs on a separately installed component that needs a license: you can evaluate it with a trial, and production use needs a license key or a runtime key from Etlworks (contact Etlworks support).

Available in Etlworks 10.0.14 and newer: administrators install, trial, license, upgrade, and remove premium connectors from the Etlworks UI — no files to copy, no restart. Before 10.0.14, Etlworks support copied files onto the server.

Where you manage them:

Connection editor: every premium connection shows a connector panel below the header with the status chip, the version, and the actions you may take: Download and install, Upload connector, Start trial, Extend trial, Activate/Change license, Remove connector. A banner under the description reads "This is a premium connector. To get a license, contact Etlworks support." until a production license is in force, then simply "This is a premium connector."

Settings → Premium connectors: the full list (columns Connector, Version, License, Servers, Notes) with a filter box and buttons + (install a connector), refresh (check all servers again), and download (JSON inventory of every server). Selecting a connector shows its detail: header chip, connector panel, and the tabs Servers, License, Versions, and History.

Who can manage premium connectors

Users without these rights see the status and "Contact your administrator…". License keys and runtime keys can only be set by super administrators.

Install a premium connector

1. Open a connection of that type, or go to Settings → Premium connectors and click +.
2. Click Download and install. The connector is downloaded from Etlworks' download location, checked (signature and checksum), and installed on every server of the environment, with no restart. The newest version is offered by default; super administrators can pick an older major version.
3. Progress shows in the panel and as a notification ("Installed on N server(s)").

Upload connector is for servers without internet access: upload the connector's .zip (or .jar) obtained from Etlworks support.

Start or extend a trial

• Start trial activates a trial license on every server. The trial period is 30 days by default; Etlworks can lengthen it, often together with the Etlworks trial.
• Extend trial starts a new trial period.
• Trials are for evaluation. A trial version may limit writes (for example, "Trial does not allow writes").
• Each server activates its own trial, and new servers added later activate automatically while the trial period lasts.

Activate a license

Use Activate license in the panel, or the License tab:

• License key: for a single server or a self-managed cluster. Use one key for all servers or (dedicated or self-hosted) a key per server. Each server uses one activation of the key.
• Runtime key: the only production option in a managed elastic cluster, and usable anywhere. It isn't tied to a machine, so nothing is activated. A runtime key is checked when a connection opens.

Details:

• Keys are stored encrypted, masked in the UI, and never appear in connections, exports, or logs.
• A key saved in Settings takes precedence over one provided by Etlworks through the license server ("from license server" is shown).
• Change license replaces a key. Remove license removes the key saved in Settings; the connector falls back to its trial if one is running, otherwise it's unlicensed.
• Legacy: a runtime key set as RTK in a connection's Other parameters still works and is used for that connection.

License status

The Servers tab shows each server's status, version, license file, machine id, and last check, plus notes such as "Unused copy in Tomcat lib" (see connectors installed in Tomcat's lib folder).

Upgrade and downgrade (Versions)

For super administrators. The Versions tab lists every downloaded or uploaded version with its source (Download / Upload / Copied from Tomcat's lib folder), date, the servers using it, and its status (Active / Available / Not supported by this release). All versions are kept until deleted.

Switch to runs three checks and shows the results before switching:

1. The version is supported by this Etlworks release.
2. Saved connections: every saved connection of the connector is checked against the new version, and properties it doesn't support are listed with the connections that use them.
3. License on every server.

Switch when all checks pass. Switch anyway is offered when only the connection check failed; those connections will fail until their properties are changed.

More rules:

• Downloading or uploading a newer version of an installed connector runs the same checks and switches automatically when they pass; otherwise the version stays available in Versions, with the reason.
• Automatic switch-back: if the new version doesn't load or its license check fails within 2 minutes on any server, every server switches back.
• Licenses across versions: within the same major version the license carries over; upgrading to a new major version on a trial starts that version's trial automatically; a downgrade uses the license that version had and is blocked with a clear message when there's none ("There's no license for version N on this server. Activate a license…"); a license key for one major version may not work for another — you're told to enter a key for that version.
• Delete removes a version that no server uses, including its license file.
• Run-time hint: if a connection uses a property the version in use doesn't support, its error ends with "The connector version in use (X) doesn't support this property."

Unload now

After a switch, connections opened earlier keep the old version until they close. Unload now (Settings, connector header) unloads older versions everywhere and closes those connections immediately.

Remove a connector

For super administrators. Remove connector (in the panel) shows the saved connections that use it. After confirmation, on every server it unloads the connector (closing open connections) and deletes all its versions and license files, plus the keys saved in Settings.

Trial history is kept, so a reinstall continues the same trial period. Connections that use the connector stop working until it's installed again.

Connectors already installed in Tomcat's lib folder

Before 10.0.14, premium connectors were installed by copying files into Tomcat's lib folder (or premium-drivers in Docker). On upgrade, Etlworks copies them, with their license files, into its own managed folder and manages them from then on. The files in lib are never changed — the copy there is simply no longer used (note "Unused copy in Tomcat lib").

To go back, choose Use the connector in Tomcat's lib folder (Versions tab), and Manage this connector to undo it.

Note: Zoho Creator no longer needs derby.jar in Tomcat's lib. Deployments that keep the connector in lib still need it.

Clusters, Docker, and managed clusters

For self-hosted and dedicated environments:

• Every action applies to all servers, with per-server results. A new server or pod installs and licenses the connectors within seconds of starting.
• If a server doesn't answer, the action finishes after a limit (10–30 minutes) with "No answer from: <server>".

Where each server keeps its connectors (outside Tomcat, never shared):

Downloaded versions are kept in the environment's shared app data.

Upgrading self-hosted installations to 10.0.14

On Linux and Windows, run etlworks-cli upgrade-cli first (it creates the managed-connectors folder), then etlworks-cli upgrade. If the folder is missing, Etlworks shows "The managed connectors folder on this server can't be written" and managed install, trial, and license are off on that server — the upgraded CLI creates the folder, or set premium.drivers.local.path to a writable folder.

Docker

Trial and license-key activations are tied to the container's host name. Set a fixed host name — hostname: etlworks-app in docker-compose.yml, or --hostname etlworks-app with docker run — and keep it for the life of the installation. If it changes, trials re-activate automatically; license keys must be activated again. A runtime key isn't affected.

Command line (self-hosted)

etlworks-cli drivers list|status [connector] [--json]

Shows each connector on that server with SOURCE (managed / lib) and license status. It works while Etlworks is stopped.

Advanced settings (application.properties, self-hosted)

• premium.drivers.local.path: the folder for this server's connectors.
• premium.drivers.managed.enabled=false: turns managed premium connectors off; connectors in Tomcat's lib keep working.
• premium.drivers.adopt.lib=false: don't copy connectors from Tomcat's lib.

Internet access: downloads and trial/key activation need outbound HTTPS to the Etlworks download location and the license service. Without it, upload the connector and use a runtime key.

Integration Agents are unchanged: premium connectors on Agents are still deployed into the Agent's lib folder.

Troubleshooting