Supporting seeds

If you configure a connector's services to enable it, users can run queries with seed records that enable or change their functionality. Your implementations of the acquire endpoint receive identity and property data from selected records that you can use to drive operations against the external data source.

The behavior of a query that supports parameters is modified by values that users specify when they run it. The behavior of a query that supports seeds is modified by the records that a user selects. Seeded queries generally fall into one of a handful of categories:

  • A "find like this" query looks at the property values of a selected record and searches for data in the external source that has the same or similar property values.

  • A "get latest" query uses the identifying information of a selected record to look for the same data in the external source, with the aim of updating the record.

  • An "expand" query uses the identifying information of a selected record to search for data in the external source that is connected to that record.

  • A "find path" query receives the identifying information for exactly two selected records and searches for a path that connects those records in the external source.

Seed constraints

To indicate that a particular service supports seeds, you add a seedConstraints object to its definition in your response from the configuration (or user configuration) endpoint. An empty object indicates that the service supports any number of entity seeds. To change this behavior, and for more control over the constraints, you can populate the object. The REST SPI documentation for the configuration endpoint describes its structure:

"seedConstraints": {
  "connectorIds": [""],
  "min": 0,
  "max": 0,
  "seedTypes": {
    "allowedTypes": "",
    "itemTypes": [
      {
        "id": "",
        "min": 0,
        "max": 0,
        "typeLocation": ""
      }
    ]
  }
}

A service can specify which records it accepts as seeds by restricting the connectors they came from. It can also set boundaries on the number of seed records it accepts, regardless of their type. A service can specify whether entity or link records are allowed as seeds (entity records are the default), and then restrict the range to a subset of that group. It can also set boundaries on the number of seeds, on a per-type basis.

If you configure the constraints so that requests must contain at least one seed of each permitted item type, then the service requires seeds. Users cannot run the service without an appropriate selection. Otherwise, your implementation of the acquire endpoint must support requests that might or might not contain seed information.

Semantic seed constraints

Alternatively, instead of specifying which item types records must have in order to be seeds, a service can specify the semantic types of properties for which a seed record must have a value. In that case, the SPI and the seed constraints look a little bit different:

"seedConstraints": {
  "min": 0,
  "max": 0,
  "seedTypes": {
    "semanticPropertyTypes": {
      "semanticPropertyTypeLabel": [""]
    }
  }
}

If you configure semantic seeds, then each seed must satisfy the full set of at least one of the semantic property type constraints. Users cannot run the service without an appropriate selection.

Note: When you specify a semantic property type as a seed constraint, the service will also accept records with values for descendants of that semantic property type as seeds. In most cases, it's better to use the most generic semantic type that is reasonable to use as a constraint.

When the i2 Connect gateway calls your acquire endpoint to perform a seeded query, it includes a payload that contains identifiers and property values for all seeds. For information about the structure of the payload, see the REST SPI documentation for the request parameter of the acquire endpoint.

Creating a seeded query

In outline, the procedure for supporting seeded queries in one of your services is to start by adding seed constraints to its configuration. Clients then interpret the configuration and present the queries to users. When users run a query, your implementation of the acquire endpoint receives seeds that you can use to guide your response.

  1. Decide what kind of seeded operation you want to perform, and its implications for the service.

    For an "expand" query, for example, you might accept a fairly large number of entities of any type as seeds. For "find like this", the seed is more likely to be a single record of a specific type, or with a value for a specific semantic property type.

  2. Add a seedConstraints object that reflects the requirements of the query, to the response from the configuration (or user configuration) endpoint.

  3. Implement the acquire endpoint for your service.

    If at least one of the constraints does not specify a minimum record count, the endpoint might be called with or without seeds. The REST SPI documentation for the acquire endpoint describes the structure of the seed data.

    Important: For "get latest" and "expand" queries, it is common for seed records also to appear in the results. In that case, you must ensure that the id of the outgoing record matches the seedId of the incoming record. In an "expand" query, for example, you can identify a seed as being one end of a link in the response by setting the fromEndId of the link to the seedId.

  4. Restart the i2 Analyze server or instruct the i2 Connect gateway to reload the configuration. Then, connect to the server with a client, log in as a user who can see the query, and ensure that the service is working properly.