Modifying and testing a connector

A connector to an external data source is defined by the information that the i2 Connect gateway retrieves from its configuration endpoint. To add a connector, or when you modify an existing one, you must arrange for the gateway to reload the information for all the connectors in the topology.

A connector that has only a configuration endpoint and an acquire endpoint is simple, but entirely functional. When you have a connector in this state, you can verify that many of the most important mechanisms are working correctly. To enable a faster test and development cycle, add new connectors to a running instance of i2 Analyze as soon as you can.

The i2 Connect gateway maintains a cache of configuration information that it provides to clients on request. Depending on the stage of development of your connector, you can use different approaches to make the gateway update its cache:

If you add or edit a <connector> element in the topology file, then you must redeploy and restart the i2 Analyze server, as described in Adding a connector to the topology.
If you modify a connector so that the response from its configuration endpoint changes - when you add a validate endpoint, for example - you do not need to redeploy the server. Instead, you can either run the restartLiberty task from the deployment toolkit, or use the i2 Connect gateway's reload endpoint.

Regardless of how you update the gateway's cache of connector configuration information, the effect for clients and their users is the same. When a client next asks for a list of the services that it can use, any changes that you made are reflected in the list.

To run restartLiberty, you can use the same technique as for any other deployment toolkit task. This section describes how to use the reload endpoint, and then explains some ways to diagnose problems with a new or updated connector.

The reload endpoint supports the POST method, which you can call through a command-line tool such as postman or curl. The endpoint requires authentication, which means that you must log in to the server and retrieve a cookie before you can POST to reload.

The following steps describe how to use curl to reload the connectors:
1. If the curl utility is not available on your server, download it from the project website at https://curl.haxx.se/download.html.
2. Open a command window and use curl to log in to the i2 Analyze server and retrieve an authorization cookie:
```
curl -i --cookie-jar cookie.txt
     -d j_username=user_name
     -d j_password=password
     http://host_name:host_port/context_root/j_security_check
```
  This command connects to the specified i2 Analyze server as the specified user, retrieves the authentication cookie, and saves it to a local file named cookie.txt.
3. Use curl a second time to call the POST method on the reload endpoint:
```
curl -i --cookie cookie.txt
     -X POST http://host_name:host_port/context_root/api/v1/connectors/reload
```
  This command causes the i2 Connect gateway to reload configuration information from all the connectors that the topology included when it was last deployed. Clients receive updated information about the connectors when they next connect to i2 Analyze.
After you reload the connectors (or restart the server), click Preview services in the server admin console to check that clients will reflect your changes in their lists of queries.
If you do not see your changes, different symptoms imply different causes:
- If a query does not appear in the list at all, then the problem lies with either the implementation of the configuration endpoint, or the <connector> element in the topology.xml file.
- If a query is in the list but marked as unavailable, then the cause of the problem is either the implementation of the acquire endpoint, or the specification of that endpoint in the response from the configuration endpoint.
- If the displayed information about a query is faulty or incomplete, look again at the definition of the corresponding service in the response from the configuration endpoint.
Provided that the queries due to new or modified connectors appear correctly, you can open a client, run them, and view the results that they return.

After you test that your connector meets your requirements, you might choose to secure the connector in your deployment. You can control user access to the connector, and secure the connection between the connector and gateway. For more information, see System security with the i2 Connect gateway.