Skip to main content

What are external connectors?

“External connectors” are connectors written for specific third-party systems (e.g. PRTG or vSphere) that usually run inside your company’s network and are therefore not accessible from the outside. So external connectors are typically used when you have a Qbilon SaaS instance and want to import data from systems inside your network – such as PRTG or vSphere. External connectors are “dockerized” versions of the built-in connectors in Qbilon and are usually executed in an on-premises Docker Compose setup. External connectors are available for Darktrace, PRTG and vSphere.

Prerequisites

  • A machine running Docker and Docker Compose:
    • The Docker engine version must be higher than 24.0.0 in order to have “docker compose” preinstalled.
    • Linux is the preferred operating system.
    • If you need to install Docker, please follow the official instructions here.
  • The machine must have access to the third-party system from which you want to retrieve data.

Setup an “External Connector”

1. Download External Connector

First, you need to set up your external connector locally. You can download the appropriate connector from our website:
Problems have been reported when trying to download these ZIPs using the Safari browser, where only one file was downloaded instead of the entire ZIP file. If you experience this, please use a different browser.

2. Create a Webhook

Follow this description to add Webhook Triggers to Qbilon:
  • Go to “Settings & Support” and create a “Webhook Trigger” (“Create trigger call+”) with a custom name.
  • The displayed URL represents the endpoint for incoming data connections that is required later.
  • Navigate to the “General” tab and click on “Generate new API key” if no one was already generated.
    • Warning: This will revoke the old key and disconnect all services that use it.
  • Finally, go to the “Automations” section and create a new “Qbilon Sink” endpoint by providing a custom name.
  • After clicking on “Next”, select “Webhook” in the “Execution Type” dropdown menu, select your webhook in the dropdown menu below and save the new task (“Next” and “Create and save new automation”). Now, we successfully combined the newly created Webhook endpoint with a Qbilon Sink automation task. Now, when an external connector sends data to Qbilon using the correct URL and API key, this Qbilon Sink automation task is triggered and stores the incoming data.

3. Configure External Connector

After unzipping the downloaded file, you need to open the “.env file” and fill in the necessary information for the connector to work properly:
  • The Qbilon settings part includes QB_WEBHOOK_URL, the QB_API_KEY and the QB_TENANT_NAME.
  • The general connector settings require the third-party system credentials and additional settings.
For URLs in the “.env file”, please make sure that they don’t end with a trailing ”/”, e.g.:

4. Run External Connector

Finally you have two options to run an external connector: “once” or “scheduled” (according to a defined time pattern). The execution type is determined by the Docker Compose profile that you selected when creating the Docker compose setup: “Once” will immediately run the connector using the values in the “.env file”. This file contains all connector parameters and differs slightly from connector to connector. The corresponding command is docker compose --profile once up. “Scheduled” runs the connector according to the schedule defined in QB_COLLECTOR_CRON. This can be CRON expressions, predefined schedules or intervals. The corresponding command is docker compose --profile schedule up . Here are some configuration examples for “scheduled”:
  • CRON expression: 0 0 0 * * * for Run once a day, midnight
  • Pre-defined schedules:
  • Interval: @every 1h30m10s or @every 10m .
Please note:
  • Since Qbilon runs in a container, the timezone is always UTC. Keep this in mind when setting up your schedule.
  • If you are running a schedule for a Docker image that isn’t available locally (e.g. a private container registry like “qbiloncr”), you’ll need to …
    • manually pull it first using docker pull <image> so that the scheduling task can use the local image.
    • Example for the vSphere connector: docker pull publicqbiloncr.azurecr.io/release/vsphere-connector:1.0.0
    • The correct image name can be found in the “.env file”.
  • Our scheduling task has no access to private repositories, even if you are logged in to the registry.

Additional Info for Scheduled Tasks

  • If a task is still running when its next execution is already due (according to the schedule), it will be skipped instead of being queued. This results in the following console output: Finished in "126.6µs", failed: false, skipped: true, error: none
  • While a task is running, you won’t receive any terminal output from that task. Instead, the task output is printed after the task has finished. However, you can view the live output in the associated Docker containers.
  • When defining a schedule in the “.env file”, be careful not to include any extra spaces or characters. For example:
    • QB_COLLECTOR_CRON="@every 1m" is correct while …
    • QB_COLLECTOR_CRON="@every 1m " will fail with an error since there is an additional space at the end.