Supporting seeded queries

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.

As you read the following information, also look at the config.json files in the example projects at https://github.com/IBM-i2/Analyze-Connect, some of which demonstrate the results of following this procedure.

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.

To indicate that a particular service supports seeds, you add a seedConstraints object to its definition in your response from the 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.

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.

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.
  2. Add a seedConstraints object that reflects the requirements of the query, to the response from the 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 and ensure that the service is working properly.

    If your service supports being used with and without seeds, then its query appears in the client's lists of seeded and "unseeded" queries. Selecting the query in either list displays information about what seeds the user can or must select before they can use it.