Adding a connector to the topology

To add a connector to a deployment of i2 Analyze that includes the i2 Connect gateway, you must provide information about it in the topology file. In that file, the <connector> element controls the behavior of the connector and the experience of its users.

Before you begin

Ensure that your deployment of i2 Analyze includes the i2 Connect gateway. If the gateway was not a part of the original deployment, you can add it by following the instructions in Adding more data sources.

About this task

Each <connector> element in the topology file ties together the URL of the server that hosts the connector, and the URL of the configuration endpoint for that connector. After you change the contents of the topology file, you must update the deployment and restart the i2 Analyze server.

Procedure

When you deploy i2 Analyze with one of the example configurations that includes the i2® Connect gateway, the topology file contains a <connectors> element. Adding a connector to the topology means adding a child to that element. (If your topology file does not contain a <connectors> element, you can also add it by hand.)

Navigate to the configuration\environment directory of the toolkit for your deployment of i2 Analyze. In a text editor, open the topology.xml file.
In the <war> element, locate the <connector-ids> child element, or add it if necessary.
Add a <connector-id> child element with the following format:
```
        <connector-ids>
          <connector-id value="ConnectorId"/>
        </connector-ids>
```
Here, ConnectorId must be unique within the topology file. Its purpose is to reference the configuration for the connector in the <connectors> element.
Add a <connector> element to the <connectors> element, which is a child of the root <topology> element:
```
<connectors>
  <connector id="ConnectorId"
             name="ConnectorName"
             base-url="Protocol://HostName:PortNumber"
             configuration-url="Protocol://HostName:PortNumber/Path"/>
</connectors>
```
Here, ConnectorName is likely to be displayed to users in the list of queries that they can run against external sources.

The i2 Connect gateway uses the value that you assign to the base-url attribute to locate the server that hosts the connector. configuration-url is the only optional attribute.

By default, the gateway retrieves initial configuration information for the connector from <base-url>/config. You can change this behavior by specifying a different URL as the value of configuration-url.
Important: Connectors created to target i2 Analyze 4.4.0 and above provide a version field in their configuration. This field enables a connector to tell the server which version of the SPI it requires. However, the new field causes a problem for a server that does not expect it.
To support using an otherwise-compatible connector on a older i2 Analyze server, you must add AllowUnknownConnectorConfigProperties=true to any settings file.

If the connector requires the gateway to send headers that contain user information, add the send-sensitive-headers attribute to the <connector> element and set its value to true:

<connectors>
  <connector id="ConnectorId"
             name="ConnectorName"
             base-url="Protocol://HostName:PortNumber"
             configuration-url="Protocol://HostName:PortNumber/Path"
             send-sensitive-headers="true"/>
</connectors>

Save the file, and then restart the i2 Analyze server.
1. On the command line, navigate to toolkit\scripts.
2. Run the following commands in sequence:
```
setup -t stopLiberty
setup -t updateConnectorsConfiguration
setup -t startLiberty
```
When the server restarts, the i2 Connect gateway makes its request to the configuration endpoint. If that endpoint is not available, the result is not an unrecoverable error. Rather, the i2 Analyze server logs the problem, and users see messages about unavailable services in the client application.

Some connectors provide services that make use of definitions from the i2 Semantic Type Library. If you deploy a connector that was developed against a newer version of the library than the one on the server, compatibility problems can occur.
If you see a server startup message that mentions semantic types, you must update the server before you can use the connector. For more information, see the Troubleshooting guide in the i2 Connect gateway documentation.

To preview what users see, and to discover the status of the configured connectors at any time, you can use the server admin console.

Open a web browser and connect to the i2 Analyze server admin console at http://host_name/opal/admin.
The admin console displays a list of connectors with their statuses. To see what the logged-in user would see in their client application, click Preview services.