Making a connector configurable

Depending on the nature of a connector, it might be necessary to allow administrators to configure some aspects of its behavior at the point of deployment. This configuration might include settings such as:

URLs, credentials, and other information for connecting to third-party services.
Controls over the behavior of a service, such as what data the service returns.

As you develop your connectors, consider what configuration settings you might include to make them as flexible as possible for their deployers. Connectors can receive settings in a number of ways:

From a configuration file only
From an environment variable only
From a configuration file with optional environment variable override

Connectors built with the i2 Connect Node SDK support configuration settings with any of the following types:

string
number
Boolean
string array
object

Note: Any array- or object-based settings that you supply through environment variables must be specified as JSON strings. For example:

["one", "two", "three"]
{"prop 1":"prop value 1", "prop 2":123, "prop 3":true}

Providing settings in a configuration file

To use file-based configuration settings, add them to the config/settings.json file. The following example contains the definition of a setting named url:

{
  "url": "https://example.com"
}

If required, you can define settings in hierarchical sections to organize them. For example:

{
  "url": "https://example.com",
  "query": {
    "timeout in seconds": 20,
    "allow wildcard searches": true,
    "document file search extensions": [".doc", ".txt", ".html"]
  }
}

Accessing configuration settings from service code

Configuration settings are only useful if you can access them from within your service! The i2 Connect API provides functionality for doing so in the settings namespace (just import settings from @i2analyze/i2connect). Each function in the namespace can access settings of different types, and is named accordingly.

For example, to read a file-based string value named url:

import { settings } from '@i2analyze/i2connect';

const url = settings.getString('url');

You can indicate that a configuration setting must be present by specifying the isRequired parameter when you attempt to fetch its value. For example:

import { settings } from '@i2analyze/i2connect';

const url = settings.getString('url', true);

The call to settings.getString() then throws an error if the setting is not found.

Environment variable substitution

The settings file also supports environment variable string substitution using the syntax ${env.ENV_VAR}, where env represents the Node.js environment.

The SDK uses dotenv to enable loading an environment into the Node.js process from a .env file in the root directory of the connector. Environment variables defined outside the .env file take precedence over the variables defined in the file.

Important: The .env file should not be distributed or checked into source control.

For example, given the following configuration files:

my-connector/config/settings.json:

{
  "apiKey": "${env.EXAMPLE_API_KEY}",
  "apiUrl": "https://${env.EXAMPLE_HOST}.com/${env.EXAMPLE_PATH}"
}

my-connector/.env:

EXAMPLE_API_KEY=abc123
EXAMPLE_HOST=foo
EXAMPLE_PATH=bar

You can access the settings like this:

my-connector/src/index.ts:

const apiKey = settings.getString('apiKey');
// "abc123"

const apiUrl = settings.getString('apiUrl');
// "https://foo.com/bar"

Handling sensitive information

Many connectors need to handle sensitive information that could pose a security risk if it were compromised, such as API keys or passwords. To safeguard such information, keep these settings outside the source code or any other files that are distributed with your connector.

When you use @i2analyze/create-connector to bootstrap a connector project, it is automatically configured so that both git and npm ignore any .env file that you create.