Seeded, parameterized search

A seeded, parameterized search is a combination of seeded and parameterized searches. This type of search passes information from an entity on the chart to the service, together with conditions that can change the behavior of your searches.

If you have any issues during this task, remember to consult the troubleshooting guide.

Configuration

To explore seeded, parameterized searches, you'll start by adding another new service to the connector.

Add a new service

The new service in this example requires both a form setting and a seedConstraints setting. For more information, see the documentation for the IServiceConfig interface, or go over the last two steps of the walkthrough.

For example:

{
  addService(
    {
      id: 'expandWithConditions',
      name: 'NYPD Connector: Expand with conditions',
      description: 'A service that executes an expand operation on a seed, with conditions.',
      seedConstraints: { typeConstraints: [Complaint], min: 1, max: 1 },
      form: {
        isPerson: { label: 'Person', logicalType: 'boolean' },
      },
    },
    () => {
      // TODO: Implement the service
    }
  );
}

Implementation

With the service defined, you can implement it to search the NYPD data source. You need to:

1. Parse the seeds to the acquire part of the service.

2. Access the condition, and use it and the seeds to query the NYPD data source.

3. Filter the NYPD data source based on the conditions and the seeds. How you use the seeds depends on what you are trying to achieve.

Filter data based on conditions and seeds

An "expand with conditions" query takes an entity as a seed and returns a list of entities and links that:

• are connected to the seed, and
• satisfy the list of conditions that the user provided.

For this service, you need to query the NYPD data source to find entities that are related to the seed entity. Then, you filter those results according to the conditions. Finally, you fabricate link records that represent the relationships. Every link record that you create must have the seed record at one of its ends.

addService(
  {
    id: 'expandWithConditions',
    name: 'NYPD Connector: Expand with conditions',
    description: 'A service that executes an expand operation on a seed, with conditions.',
    seedConstraints: { typeConstraints: [Complaint], min: 1, max: 1 },
    form: {
      isPerson: { label: 'Person', logicalType: 'boolean' },
    },
  },
  async ({ conditions: { isPerson }, seeds, result }) => {
    const seed = seeds.entities[0];
    const complaintNumber = (seed.isType(Complaint) && seed.getProperty('Complaint Number')) || '';

    const data = await requestData({
      $limit: '50',
      $where: `cmplnt_num="${complaintNumber}"`,
    });

    const seedEntity = result.addEntityFromSeed(seed);

    for (const datum of data) {
      if (isPerson) {
        const suspectEntity = addSuspect(datum, result);
        const victimEntity = addVictim(datum, result);

        addLink(Suspectof, datum.cmplnt_num, suspectEntity, seedEntity, result);
        addLink(Victimof, datum.cmplnt_num, victimEntity, seedEntity, result);
      }

      const locationEntity = addLocation(datum, result);
      addLink(Locatedat, datum.cmplnt_num, seedEntity, locationEntity, result);
    }
  }
);

Reload the connector configuration in i2 Analyze

To make the new service available, you must reload the connector so that i2 Analyze picks up the configuration changes. Just like when you deployed the connector for the first time, you can use the Admin Console.

1. Open a web browser and navigate to https://i2analyze.eia:9443/opal/admin#/connectors.

2. If you are prompted to log in, enter Jenny and Jenny as the username and password.

3. Click the Reload gateway button.

Investigate in Analyst's Notebook

Now you can see what happens when you use the connector from the Analyst's Notebook desktop client.

1. Open Analyst's Notebook and log in when prompted.

2. Select an entity that you retrieved from the NYPD data source on the chart.

3. Click the External Searches button in the ribbon. Find the query named NYPD Connector: Expand with conditions.

4. Click Open to display the search form.

5. Set the condition, and then click Run to send the parameter to the service, which queries the data source and returns results.

Next steps

Now that you've completed this task, you can look into validating service requests.