Seeded search

A seeded search passes information from an entity on the chart to the connector so that you can use that information to drive your searches. In order to pass an entity as a seed, users can select an entity in Analyst's Notebook and open "External Search".

Again, if you face any issues during this task, remember to consult the troubleshooting guide.

For more information on seeded queries, see Supporting seeds.

Configuration

You need to configure a service to allow for seeded searches.

Add a new service

Add two new services for seeded searches to the services array in the config.json file. The services should also define the seedConstraints object that controls the entities that are allowed by the seeded search.

{
  "services": [
    {
      "id": "nypd-find-like-this-complaint-service",
      "name": "NYPD Connector: Find like this complaint",
      "description": "A service that finds a similar complaint.",
      "acquireUrl": "/find-like-this-complaint",
      "seedConstraints": {
        "min": 1,
        "max": 1,
        "seedTypes": {
          "allowedTypes": "ENTITY",
          "itemTypes": [
            {
              "id": "made-up-schema-type-id (e.g. ET1)",
              "min": 1,
              "max": 1
            }
          ]
        }
      }
    },
    {
      "id": "nypd-expand-service",
      "name": "NYPD Connector: Expand",
      "description": "A service that executes an expand operation on a seed.",
      "acquireUrl": "/expand",
      "seedConstraints": {
        "min": 1,
        "max": 1,
        "seedTypes": {
          "allowedTypes": "ENTITY",
          "itemTypes": [
            {
              "id": "made-up-schema-type-id (e.g. ET1)"
            },
            {
              "id": "made-up-schema-type-id (e.g. ET1)"
            }
          ]
        }
      }
    }
  ]
}

We will cover these two types of seeded queries later in this topic. For now, update the ids of the itemTypes to values that exist in your schema.

Check service in Analyst's Notebook

Reload the connector and check that your services are in the list of defined services in Analyst's Notebook.

  1. Open a web browser and navigate to <i2-Analyze-URL>/admin#/connectors, where <i2-Analyze-URL> is the URL used to access your i2 Analyze deployment. For example, http://localhost:9082/opaldaod/admin#/connectors.

    Note: For more information about the Admin Console, refer to i2 Analyze Server Admin Console.

  2. If you are prompted to log in, enter the credentials for your default user. If you added an example user, the username and the password will be Jenny.

  3. Click Reload gateway to enact your changes.

  4. Log out and log back in to Analyst's Notebook to see the configuration changes and your newly defined service.

  5. You may notice that you are not able to run any of the new services. Since they are seeded services, you must first select a valid seed. Run one of the valid services defined in previous topics and copy the entities to the chart.

  6. Select one of the entities. If the entity type matches the valid seed type defined by the seeded service, that service will become available to execute.

  7. Run the seeded service.

You should receive an error as your seeded search has been defined but not yet implemented.

Implementation

It's time to implement the service.

Add an acquire endpoint for your service

Java

i2 Analyze knows the acquire URL for this service. Now you need to add the corresponding endpoint in the connector.

Define the seeded search endpoint in the ConnectorController class as below:

/**
  * Defines the seeded search endpoint which acquires the seeded search data (entities and links
  * based on seeds)
  *
  * @param request The request containing the payload.
  * @return The resulting entities and links connected to the selected entities.
  */
@RequestMapping(
      method = RequestMethod.POST,
      value = "SEEDED SEARCH ACQUIRE URL GOES HERE",
      consumes = APPLICATION_JSON_VALUE,
      produces = APPLICATION_JSON_VALUE)
public I2ConnectData testSeededSearchService(@Valid @RequestBody DaodRequest request) {
  // TODO: Extract seed information and use it to search
  System.out.println(request.payload.seeds);
  return connectorDataService.retrieveTestDataFromExternalSource(/*seeds*/ );
}

You must update the value field in the @RequestMapping object with the acquireUrl defined by your seeded service in config.json.

Python

i2 Analyze knows the acquire URL for this service. Now you need to add the corresponding endpoint in the connector.

Define the seeded search endpoint in the controller.py class, as below:

@controller.route('SEEDED SEARCH ACQUIRE URL GOES HERE', methods=['POST'])
def seeded_search():
    """
    Defines the seeded search endpoint which acquires the
    seeded search data (entities and links based on conditions)
    """
    print(request.json['payload']['seeds'])

    # TODO: Extract seeded information and use it to search

    return query_external_datasource()

You must update the @controller.route value with the acquireUrl defined by your seeded service in config.json.

Access seeds

You will need to manipulate a seed passed into the request according to the SPI, and return a response containing entities and links.

Filter data based on seed

How you will use the seed depends on what you are trying to achieve.

  • 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.
  • For this service you will need to filter out your entities based on the matching properties of the seed entity that can be accessed via request.payload.seeds.entities.get(0).
  • Note: Do not return the entity that was passed as the seed.
  • An Expand query takes an entity as a seed and returns a list of entities and links that are connected to the seed.
  • For this service you will need to find all links connected to the seed entity that can be accessed via request.payload.seeds.entities.get(0). Then you will need to find all entities connected to these links.
  • Finally, you need to make sure that the link is pointing to the seedId.
  • To do that, you will need to change toEndId or fromEndId to the seedId that can be accessed via request.payload.seeds.entities.get(0).sourceIds.get(0).key.get(2).

For more information about these and other uses for seeded searches, see Supporting seeds.

Run your query

Run the seeded search service in Analyst's Notebook.

  1. Redeploy the connector. Depending on how you are running the connector, this may be done automatically for you when changes are made.

  2. Open Analyst's Notebook.

  3. Select an entity on the chart.

  4. Click "External Search".

  5. Click your seeded search service to run it.

You should now see a list of result entities that are connected to the entity you initially selected.

Next steps

Next, you can combine what you've learned from these past two sections to implement seeded parameterized searches.