Modifying and testing

A connector to an external data source is defined by the information that the i2 Connect gateway retrieves from its configuration endpoints. 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. In general, to enable faster test and development cycles, 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.
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.

Note: For a connector that supports user-specific configuration, the i2 Connect gateway maintains per-user caches of configuration information. Using the reload endpoint clears the caches for all users. The per-user caches are not re-created until a user makes a new request to the connector.

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, or through the i2 Analyze Server Admin Console.

To trigger the reload endpoint, you can use one of the following options:
- 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.
- Postman
  
  To use Postman to reload the connectors, follow the steps described here.
- i2 Analyze Server Admin Console
  
  The following steps describe how to use the Admin Console to reload the connectors:
  1. Open a web browser and navigate to <i2-Analyze-URL>/admin#/connectors, where <i2-Analyze-URL> is the URL used to access your i2 Analyze deployment. For example, http://localhost:9082/opaldaod/admin#/connectors.
  2. If you are prompted to log in, enter the credentials for your default user. If you added an example user, the username and the password will be Jenny.
  3. Click Reload gateway to reload your connectors.
  For more information about the Admin Console, refer to i2 Analyze Server Admin Console.
After you reload the connectors (or restart the server), click Preview services in the Admin Console to check that users will see 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 might lie with either the implementation of the configuration endpoint, or the <connector> element in the topology.xml file.
  
  If the connector supports user-specific configuration, there might be a problem with the user configuration endpoint, or you might be logged in as a user whose configuration does not list the query in question.
- 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 or user 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.