Implementing a configuration endpoint

The configuration endpoint of a connector must respond to requests from the i2 Connect gateway with a JSON structure that describes the services in the connector. The more sophisticated the connector, the more information you need to provide.

Navigate to the source code for any of the connector projects in the connector directory of the Analyze-Connect repository. In a text editor, open one of the config.json files that implements the configuration endpoint and demonstrates an approach that you might take.

When the i2® Analyze server starts, the i2 Connect gateway sends a request to the configuration endpoint. The response that your connector sends back tells the gateway what services are available. i2 Analyze caches this information and provides it to clients when they connect.

The simplest possible service does not support seeds and does not require users to provide parameters. As a result, it does not require the client to display user input controls. In that case, the structure that you return from the configuration endpoint must contain only two objects:

The defaultValues object is mandatory.
Within the defaultValues object, you must specify the timezone for the i2 Connect gateway to apply to any retrieved value that does not specify its own timezone. There are also some optional settings:
- You can specify a direction for any retrieved link that does not specify its own direction.
- You can specify the identifiers and locations of the entity and link types that the i2 Connect gateway applies to records if a service does not indicate the types of data that it can retrieve.
- You can provide a default setting for whether the data identifiers that the connector returns are persistent from one call to the next.
  Note: If you do not indicate whether these identifiers are persistent here or in the services array, the gateway assumes that the identifiers are not persistent.
The services array is also mandatory.
The services array must contain information for at least one synchronous or asynchronous service. The information must include a unique identifier and a name for the service. It must also specify whether the service requires a client UI, and the URL of the acquire or queriesResource endpoint.

First, construct the defaultValues object:

Determine the timezone that is most likely to apply to any temporal data in the source that the services in this connector query.
Find the identifier of the timezone in the IANA Time Zone Database, and arrange for the response from the endpoint to include the identifier in its defaultValues object.
For example:
```
{
  "defaultValues": {
    "timeZoneId": "Europe/London",
    ...
  },
  "services": [
    ...
  ]
}
```
Note: You can also retrieve a list of supported timezones from the GET method on the i2 Analyze server's /api/v1/core/temporal/timezones REST endpoint.
If the source contains only a few types, and if you intend the connector eventually to have many services that run different queries, then consider adding an entityTypeId and a linkTypeId to the defaultValues object.

It is more common to specify what types of record a query might retrieve on a per-service than on a connector-wide basis. However, if you do not supply default types here, then every service must supply types individually.

The gateway searches for the types that you supply here in the connector schema, the gateway schema, and the Information Store schema. To specify exactly where the types are defined, you can add entityTypeLocation and linkTypeLocation properties.
If you know that the source will always attach the same identifier to the same piece of retrieved information, add the resultIdsPersistent field to the defaultValues object and set its value to true.

Then, add an object to the services array:

To the services array, add a service object that has an id and a name. It is common to include a description and populate the resultItemTypeIds array as well, although neither is mandatory.

For example:

{
  "defaultValues": {
    "timeZoneId": "Europe/London",
    "resultIdsPersistent": true
  },
  "services": [
    {
      "id": "nypd-service",
      "name": "NYPD Connector: Get All",
      "description": "A service that retrieves all data",
      "resultItemTypeIds": {
        "INFOSTORE": ["ET1", "ET2", "ET3", "LT1", "LT2", "LT3"]
      },
      ...
    }
  ]
}

For a service whose query does not allow callers to provide parameters, you can set the clientConfigType to NONE.

{
  "defaultValues": {
    "timeZoneId": "Europe/London",
    "resultIdsPersistent": true
  },
  "services": [
    {
      "id": "nypd-service",
      "name": "NYPD Connector: Get All",
      "description": "A service that retrieves all data",
      "resultItemTypeIds": {
        "INFOSTORE": ["ET1", "ET2", "ET3", "LT1", "LT2", "LT3"]
      },
      "clientConfigType": "NONE",
      ...
    }
  ]
}

If you later add parameters to the query, you can allow users to specify them by changing the value to FORM and providing the identifier of a client configuration in clientConfigId.

If you later add support for seeds, you must add a seedConstraints object to the service.

Finally, for a synchronous service, set the acquireUrl of the service to the URL where you intend to host the acquire endpoint.

{
  "defaultValues": {
    "timeZoneId": "Europe/London",
    "resultIdsPersistent": true
  },
  "services": [
    {
      "id": "nypd-service",
      "name": "NYPD Connector: Get All",
      "description": "A service that retrieves all data",
      "resultItemTypeIds": {
        "INFOSTORE": ["ET1", "ET2", "ET3", "LT1", "LT2", "LT3"]
      },
      "clientConfigType": "NONE",
      "acquireUrl": "/all"
    }
  ]
}

This JSON structure represents (almost) the simplest response that you can send from the configuration endpoint of a connector. It contains the definition of one simple service. In order for the i2 Connect gateway to retrieve that definition, you must add details of the connector to the i2 Analyze deployment topology.