Managing connectors

The /connector-images directory contains the files that are required to build each connector image in your config dev environment.

The complete contents of each connector directory depends on the template that you used to create it. All the templates include a folder that you use to place the connector source code, the files used to build the Docker images and run the Docker containers, and JSON files that you use to provide information about the connector.

For instructions about how to add connectors to your environment, see Adding connectors to your development environment.

Connector versioning

You specify the version and tag of a connector in the connector-version.json file of each connector.

  • version
    • The version value is used as a version for your connector. If you are deploying an i2 Connect server connector, the version value has more requirements. For more information, see i2 Connect server connector versioning.
  • tag
    • The tag value is used in the image name, host name, and secrets for your connector container.

For example:

{
    "version": "1.0.0",
    "tag": "1"
}

As a best practice, you should increment the version of a connector when you make changes to the connector, this usually corresponds to the version of the connector in the package.json file or pom.xml (depending on your connector type). The tag doesn't follow the same rules, you can use any value that you want. We recommend that you use the major version of the connector as the tag. If you change the tag, you must regenerate the secrets for that connector, see Connector secrets for more information.

Building connectors

Use the deploy command to generate secrets and build the images for connectors referenced in that config.

For example, to build and run all of the connectors referenced in the <config-name> config, run:

deploy -c <config_name>

To build the images for all connectors in your environment, see Managing the environment.

Connector secrets

Before you can use a connector, you must generate secrets for it. For more information about the secrets used in the environment, see Managing container security.

The secrets that are generated for a particular connector are tied to the tag, if you change the tag you must to regenerate the secrets for that connector.

To regenerate the secrets for a connector after you change the tag, complete the following steps:

  1. Remove the environment-secrets/generated-secrets/certificates/<connector_name> and environment-secrets/simulated-secret-store/<connector_name> directories for the connector that you changed the tag of.

  2. Run the deploy command with a config that references the connector.

    deploy -c <config_name>

Note: For external connectors, you must add environment-secrets/generated-secrets/certificates/externalCA/CA.cer to the trust store of the connector.

i2 Connect server connectors

If you are deploying one or more connectors that were developed using the i2 Connect SDK. There are two versions that you must consider; the version of a connector and the version of the i2 Connect server that the connectors depends on.

Connector version

In the connector-version.json file, the version specifies the range of supported versions for the connector. This enables you to have more control of the version of a connector that is used in your deployment.

You can specify the range of versions at the major, minor, or patch level. For example, if you specify a major version 1 in the connector-version.json file, any connector that has a major version of 1 is compatible.

When the connector is developed, the version of the connector is provided in the package.json file by the developer. If the version of the connector specified in package.json does not match the version, or range of versions, that you specify in connector-version.json a warning is displayed when you deploy your environment.

The following table demonstrates how you can specify the version ranges and their compatibility with connector versions:

package.json version connector-version.json version Compatible? (Y/N)
1.0.0 1 Y
1.3.0 1 Y
1.4.0 1.3 N
1.4.6 1.4 Y
1.4.8 1.4.7 N
2.0.0 1 N

i2 Connect server version

i2 Connect server connectors depend on the i2 Connect server. When the connector is developed, the version of the i2 Connect server that the connector depends on is provided in the package.json file by the developer.

In the connector-images/i2connect-server-version.json file, you specify the range of versions of the i2 Connect server that you want all i2 Connect server connectors to depend on.

The versions in these files are specified in the npm semantic versioning syntax. For more information about the syntax, see semver - the semantic versioning for npm.

If the version of the i2 Connect server that a connector depends on specified in package.json does not match the version, or range of versions, that you specify in i2connect-server-version.json a warning is displayed when you deploy your environment.

The following table demonstrates how you can specify the version ranges and their compatibility with i2 Connect server versions:

package.json version connector-version.json version Compatible? (Y/N)
^1.0.0 ^1.0.0 Y
1.3.2 ^1.0.0 Y
1.4.0 1.3.0 N
2.0.0 ^1.0.0 N

i2 Connect server connector configuration (Optional)

i2 Connect server connectors can have specific connector configuration that is defined in the settings.jsonfile. When the connector is developed, a default file can be provided by the developer. The developer should also provide you with documentation that described the required configuration for the connector.

After the first deployment of the connector, if a settings.json file is provided, the system extracts it to the connector-images/<connector-name>/app directory.

The file is in the same directory structure as in the supplied connector. For example, <connector-name>/app/config/settings.json. To change the configuration, modify the settings.json and redeploy the environment.

You might have to provide secrets, or references to secrets, in the settings.json file. To provide the secrets, you can use a value from the environment. This can either be an environment variable or a value from a .env file in the connector-image/<connector-name> directory.

Note: If you use a .env file, it must not be checked in to source control or distributed to prevent compromising your secrets.

An example settings.json file might look like:

{
  "data_source_url": "https://data-source/data.json",
  "data_source_API_key": "${env.API_KEY}"
}

Where API_KEY is an environment variable or a key in a .env file with the value of the API Key.

For more information about populating the settings.json file, see Making a connector configurable.