Parameterized search

A parameterized search enables users to pass conditions in their requests that you can use to change the behavior of your searches.

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

Configuration

To explore parameterized searching, you'll start by adding a new service to the connector.

Add a new service

Add another service to your index.ts file, and provide a form configuration. The form allows you to specify conditions through fields that are displayed to users in Analyst's Notebook, for example.

addService(
  {
    id: 'findComplaint',
    name: 'NYPD Connector: Search',
    description: 'A service for conditional searches.',
    form: {
      borough: {
        label: 'Borough name',
        logicalType: 'selectedFromList',
        isMandatory: true,
        possibleValues: [],
      },
      lawCategory: {
        label: 'Law category',
        logicalType: 'selectedFromList',
        isMandatory: true,
        possibleValues: [],
      },
    },
  },
  () => {
    // TODO: Implement the service
  }
);

Note: This form contains two mandatory fields, which means that users are forced to open it and provide values before they can run the service. If there are no mandatory fields but you still want users to see the form, you can use the formIsMandatory property to make the form itself mandatory. For more information, see Validation.

Implementation

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

1. Parse the conditions to the acquire part of the service, defining both borough and lawCategory conditions.

2. Use those conditions to query the NYPD data source.

3. Filter the NYPD data source based on those conditions. You can use the condition fields to determine which of the entities retrieved from the data source match the parameters given by the user in the form.

4. Create and return Complaint entities based on the matched conditions.

For example:

addService(
  {
    id: 'findComplaint',
    name: 'NYPD Connector: Search',
    description: 'A service for conditional searches.',
    form: {
      borough: {
        label: 'Borough name',
        logicalType: 'selectedFromList',
        isMandatory: true,
        possibleValues: [
          { displayValue: 'Brooklyn', value: 'BROOKLYN' },
          { displayValue: 'Bronx', value: 'BRONX' },
          { displayValue: 'Manhattan', value: 'MANHATTAN' },
          { displayValue: 'Queens', value: 'QUEENS' },
          { displayValue: 'Staten Island', value: 'STATEN ISLAND' },
        ],
      },
      lawCategory: {
        label: 'Law category',
        logicalType: 'selectedFromList',
        isMandatory: true,
        possibleValues: [
          { displayValue: 'Felony', value: 'FELONY' },
          { displayValue: 'Misdemeanor', value: 'MISDEMEANOR' },
          { displayValue: 'Violation', value: 'VIOLATION' },
        ],
      },
    },
  },
  async ({ conditions: { borough, lawCategory }, result }) => {
    const data = await requestData({
      $limit: '50',
      $where: `boro_nm="${borough}" AND law_cat_cd="${lawCategory}"`,
    });

    for (const datum of data) {
      addComplaint(datum, 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. Click the External Searches button in the ribbon bar. You should see the service named NYPD Connector: Search.

3. Click Open to display the search form.

4. Provide values for the two conditions, and then click Run to send the parameters to the service, which queries the data source and returns results.

Next steps

Now you can implement seeded searches.