Adding a connector to the topology

When you have an implementation of a configuration endpoint, you can tell i2® Analyze about the connector that it describes by adding it to the topology file. In that file, the <connector> element controls the behavior of the connector and the experience of its users.

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.

Each <connector> element in the topology file ties together the URL of a server, which might host several connectors, and the URL of the configuration endpoint for a particular connector. After you change the contents of the topology file, you must update the deployment and restart the i2 Analyze server.

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 as the stem for the URLs that you specify in the configuration (such as /exampleSearch/acquire). configuration-url is the only optional attribute.

By default, the gateway attempts to retrieve the configuration from <base-url>/config. You can change this behavior by specifying a different URL as the value of configuration-url.
Save the file, and then update the deployed connectors configuration and 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 (or any of the endpoints in the retrieved configuration) 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.

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 a user with access to all connectors sees in their client application, click Preview services.