Seeded parameterized search

Simply put, 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 connector together with conditions that are used to drive searches.

Should you have any problems during this task, please consult the troubleshooting guide.

Configuration

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

Add a new service

You will need to set the clientConfigId value similarly to configuring parameterized search. You will also need to add seedConstraints to define constraints on the seed, similar to configuring seeded search. For example:

{
  "services": [
    ...
    {
      "id": "nypd-expand-with-conditions",
      "name": "NYPD Connector: Expand with conditions",
      "description": "A service that executes an expand operation on a seed, with conditions.",
      "clientConfigId": "expandForm",
      "acquireUrl": "/expand-with-conditions",
      "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)"
            }
          ]
        }
      }
    }
  ]
}

Optionally, you can also define the type location for the item type with the field typeLocation. This can be used to determine in which schema the item type resides. Possible value are 'CONNECTOR', 'GATEWAY' and 'INFOSTORE'. The itemTypes object will look like this:

{
  "seedTypes": {
    ...
    "itemTypes": [
      {
        "id": "made-up-schema-type-id (e.g. ET1)",
        "typeLocation": "CONNECTOR"
      }
    ]
  }
}

You will also need to provide a clientConfig with the id set to the same value as in the service configuration, and the type defined as FORM. It should look something like this:

{
  ...
  "clientConfigs": [
    {
      "id": "expandForm",
      "type": "FORM",
      "config": {
        "sections": [
          {
            "conditions": [
              {
                "id": "made-up-id (e.g. searchBorough)",
                "label": "made-up-field (e.g. Borough)",
                "logicalType": "SINGLE_LINE_STRING"
              }
            ]
          }
        ]
      }
    }
  ]
}

You can change these conditions to relate to your own schema and what you want to search for.

Check the service in Analyst's Notebook

Let's check that your service now appears 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. Try running it. You should receive an error as your seeded, parameterized search has been defined but not yet implemented.

Implementation

It's time to implement the seeded, parameterized search.

Add an acquire endpoint for your service

In the same fashion as the other services you have defined, add an acquire endpoint for this service in your controller file.

Access conditions and seeds

You will need to manipulate the seeds and conditions passed in the request according to the SPI, and return a response containing entities and links. The conditions and seed information can be accessed through request.payload.

Filter data based 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 that satisfy the list of conditions provided by the user.

For this service, you will need to find all links connected to the seed entity that also satisfy your conditions. In the example, only links that had been created after the date provided by the user were returned. 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 through request.payload.seeds.entities.get(0).sourceIds.get(0).key.get(2).

Run your query

  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 on "External Search".

  5. Click on your seeded, parameterized search service.

  6. Provide a value to the condition field and click Run.

You should now see a list of result entities that are connected to the entity you initially selected and also satisfy the conditions you defined.

Next steps

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