Implementing config

The configuration endpoint of a connector must respond to requests from the i2 Connect gateway with information about the schemas that the connector uses and the services that it provides. In some more complex connectors, the configuration endpoint can indicate in its response that more information is available from other endpoints.

Note: Starting with version 4.4.0 of i2 Analyze, a connector can tell the gateway what version of the SPI it needs to use. If the response from your configuration endpoint does not indicate the version, the gateway assumes that the connector uses version 1.0 of the SPI. For more details, see SPI version negotiation.

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

Note: Some connectors support user-specific configuration, where different users see different views of the services that the connector exposes. In those circumstances, a static list of services is not appropriate. Instead, the configuration endpoint provides the location of the user configuration endpoint, which provides per-user information about the connector's services.

The simplest possible service does not behave differently for different users, 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.

Within the defaultValues object, there are some optional settings that can be included:
- You can specify the time zone for the i2 Connect gateway to apply to any retrieved value that does not specify its own time zone. If not specified, the gateway will default to UTC.
- 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.

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 time zone 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 time zone 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 time zones 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.

The effect of the field depends on your deployment of i2 Analyze:
- If the deployment contains only the i2 Connect gateway, then setting "resultIdsPersistent": true prevents duplication when the same record is returned twice from the same connector. Each time the record is sent to a chart, it replaces the existing version.
- In other scenarios (if the deployment also contains the Information Store, or if you set "resultIdsPersistent": false), records can be duplicated on the chart unless you configure source identifier matching in the match rules.
Note: The resultIdsPersistent field is also valid at the per-service level, where its value overrides any connector-wide setting.

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"]
      },
      ...
    }
  ]
}

If you are using SPI version 1.0 or 1.1, then you must set the clientConfigType to NONE. The clientConfigType field is not required or supported when using SPI 1.2 or later.
```
{
  "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.