Using types from different schemas

Simply creating and deploying gateway and connector schemas does not automatically make the item types that they define available to your connectors. When you want to use gateway or connector schemas, you must specify them in the connector configuration, or the i2 Analyze deployment topology, or both.

These instructions assume that you already created gateway and connector schemas that define entity and link types for the data that your connector retrieves, as described in Adding types to an i2 Analyze deployment.

Anywhere a connector can specify an item type, it can also specify which schema that type is defined in: the Information Store, a gateway, or the connector schema. For the mechanism to work, the connector must provide information in its configuration about the gateway or connector schemas that it wants to use.

Although a deployment of i2 Analyze can support several gateway schemas, an individual connector can use types from only one of them. You choose which gateway schema to use by adding its name to the response from the configuration endpoint.

  1. At the top level of the configuration response, add and populate the gatewaySchema property.
    {
      "gatewaySchema": "Example",
      "defaultValues": {
        ...
      },
      "services": [
        ...
      ]
    }

    Provided that a gateway schema with the short name EXAMPLE is configured in the ApolloServerSettingsMandatory.properties file for the deployment, the types in that schema are available for use in the connector.

To enable a connector schema, you must add endpoints for retrieving it to any connector that uses it, and then specify the locations of those endpoints in the response from the configuration endpoint.

  1. Make your connector schema and its charting scheme available through two simple HTTP GET methods that do not require parameters.
    It is easiest, but not mandatory, to implement these endpoints on the server that hosts the connectors that use them.
  2. Add schemaUrl, chartingSchemesUrl, and schemaShortName settings to the response from your implementation of the configuration endpoint:
    {
      "schemaUrl": "/schema",
      "chartingSchemesUrl": "/chartingSchemes",
      "schemaShortName": "Another-Example"
      "defaultValues": {
        ...
      },
      "services": [
        ...
      ]
    }
    In this form, i2 Analyze appends the URLs that you provide to the base-url that you specified for the connector in the topology file. By definition, these endpoints are on the same server as the connector. To use endpoints that are implemented elsewhere, you must provide the full URLs here.

Making changes like these affects the connector but not the topology, so you do not need to redeploy i2 Analyze. Restarting the server or using the reload endpoint on the i2 Connect gateway is enough.

  1. Follow the steps in Modifying and testing a connector to restart the server or force the gateway to reload your connector configuration.
    The new types become available for use.

With the above changes in place, and provided that there are no identifier clashes, the connector can use item types from the connector, gateway, or Information Store schema just by using their identifiers. i2 Analyze searches for types in all three schemas, in that order. It is also possible to specify which schema a particular item type comes from:

  • When you are specifying the default return types for the connector as a whole, you can set the entityTypeLocation and linkTypeLocation properties.
  • When you are specifying the possible return types from a service, you can provide locations in the resultItemTypeIds structure.
  • In each record that you return from a service, you can set the typeLocation property.

When you deploy a connector, you can use the <connector> element in the topology file to override some of the schema settings in the connector. You can instruct the connector to use a gateway schema with a different short name, which can be useful if you were unable to deploy the schema with the name that the connector expected. You can also change the short name of the connector schema, which is useful if you have two connectors that advertise the same name.

  1. To specify a gateway schema with a different short name, add the gateway-schema attribute to the <connector> element:
    <connectors>
      <connector id="ConnectorId"
                 name="ConnectorName"
                 base-url="Protocol://HostName:PortNumber"
                 gateway-schema="ShortName"/>
    </connectors>
  2. To provide a different short name for the connector schema, add the schema-short-name attribute to the <connector> element:
    <connectors>
      <connector id="ConnectorId"
                 name="ConnectorName"
                 base-url="Protocol://HostName:PortNumber"
                 schema-short-name="NewShortName"/>
    </connectors>

    After you make changes to the topology of an i2 Analyze deployment, you must update the deployed connectors configuration and restart the i2 Analyze server, as described in Adding a connector to the topology.