Parameterized search

A parameterized search passes defined conditions that you can use to drive your searches. For more general information about enabling parameterized searches, see Supporting parameters.

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

Configuration

Add a new service

To define a parameterized search, the service requires a client configuration. Let's begin by defining a service with a clientConfigId field in config.json.

{
  "version": "1.2",
  "services": [
    {
      "id": "nypd-search-service",
      "name": "NYPD Connector: Search",
      "description": "A service for conditional searches.",
      "clientConfigId": "searchForm",
      "acquireUrl": "/search"
    }
  ]
}

Define search fields

Since you specified a clientConfigId for the service, you must now define the configuration.

Add a clientConfigs array to the root level of config.json with an entry for the client configuration identifier. For example:

{
   "version": "1.2",
   "services": [
      ...
   ],
   "clientConfigs": [
      {
         "id": "searchForm"
      }
   ]
}

Set the type value in the client configuration entry to be FORM so that you can specify your conditions through fields in a form that will be shown in Analyst's Notebook.

To define the search fields for the form, add a form config object as below:

{
   "version": "1.2",
   "services": [
      ...
   ],
   "clientConfigs": [
      {
         "id": "searchForm",
         "type": "FORM",
         "config": {
            "sections": [
               {
                  "conditions": [
                     {
                        "id": "searchTerm",
                        "label": "made-up-field (e.g. Complaint Number)",
                        "mandatory": false,
                        "logicalType": "SINGLE_LINE_STRING"
                     }
                  ]
               }
            ]
         }
      }
   ]
}

For more information about client configuration, refer to the development workflow documentation.

Test search fields

Reload the connector and check that your fields work in Analyst's Notebook.

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.
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.
Click Reload gateway to enact your changes.
Log out and log back in to Analyst's Notebook to see the configuration changes and your newly defined service.
Try running the query. You should receive an error because your condition fields have been defined but not yet implemented.

Implementation

It's time to implement these conditions.

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 new endpoint in the ConnectorController class as below:

/**
* Defines the /search endpoint which retrieves entities and links based on conditions.
*
* @param request The request containing the payload.
* @return The resulting entities and links after a conditional search.
*/
@RequestMapping(
   method = RequestMethod.POST,
   value = "/search",
   consumes = APPLICATION_JSON_VALUE,
   produces = APPLICATION_JSON_VALUE)
public I2ConnectData testSearchService(@Valid @RequestBody DaodRequest request) {

   // TODO: Extract request conditions and use in request to Socrata.
   System.out.println(request);
   return connectorDataService.retrieveTestDataFromExternalSource(/*search params*/ );
}

Look at how the endpoint is defined and think about how you should implement this service.

Python

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

Define the new endpoint in the controller.py class as below:

@controller.route('/search', methods=['POST'])
def search():
    """
    Defines the /search endpoint which acquires the 
    search data (entities and links based on conditions)
    """
    print(request.json)

    # TODO: Extract request conditions and use in request to Socrata.
    # Pass conditions into your function.

    return query_external_datasource()

Don't forget to add the import for request! Your import should look like this:

from flask import Blueprint, request, send_from_directory

Look at how the endpoint is defined and think about how you should implement this service.

Access conditions

You will need to parse the conditions passed in the request according to the SPI, and return a response containing entities and links. The list of conditions can be accessed via request.payload.conditions.

For an example of how your connector might receive requests, and the responses it might return, you can view some SPI examples here.

Filter data by conditions

When you have a list of conditions, you can use their id and value fields to determine which of the entities retrieved from the data source match the parameters given by the user in the form.

Run your query

Reload the connector and check that your fields work in Analyst's Notebook.

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.
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.
Click Reload gateway to enact your changes.
Log out and log back in to Analyst's Notebook to see the configuration changes and your newly defined service.
Select your parameterized search service.
Provide a value to the condition field and click Run.

You should now see a list of result entities that satisfy your condition.

Next steps

Now you can implement seeded searches.