Adding a connector with a connector schema to an existing deployment

In this example scenario, we will add a new connector with its own connector schema to an i2 Analyze deployment with an existing gateway schema. Item types in the connector schema will be mapped to item types in the gateway schema where possible.

Note: These instructions can also apply to mapping item types from one gateway schema to another gateway schema.

Setting up the scenario

To follow this example, start by deploying i2 Analyze with the example NYPD connector, as described in the analyze-connect repository, with the connector configured to use a gateway schema.

With the example deployment in place, you can connect to the i2 Analyze server from Analyst's Notebook and use the services provided by the NYPD connector. For example, you might use the "Get All" service and copy some of the results to a chart.


NYPD records

Adding a second connector

Next, add the example KCPD connector to the deployment, ensuring that it is configured to use its own connector schema.

When the connector is deployed, you should be able to use the services that it provides and copy some results to the chart.


Unmapped NYPD and KCPD records

The image uses highlighting and different icons to show how the gateway schema used by the NYPD connector and the connector schema used by the KCPD connector use different item types to model the same real-world objects.

Looking at all the available item types, you can see that both schemas have their own:

  • 'Person' entity type

  • 'Location' entity type

  • 'Complaint'/'Report' entity type (different names, but modeling the same concept)

  • 'Located At' link type

  • 'Suspect Of' link type

  • 'Victim Of' link type

You can use type conversion mappings to resolve this duplication.

Configuring item type mappings

In a web browser, go to the the i2 Analyze Type Conversion app in the i2 Analyze Server Admin Console to see the list of item types that can be mapped. You should see a list of all item types in the KCPD-Crime schema, and that none of them has been mapped.


Unmapped KCPD-Crime item types

Where appropriate, KCPD-Crime item types can be mapped to similar item types in the NYPD-Complaints gateway schema.

Report and Complaint

The Report entity type in the KCPD-Crime schema can be mapped to the Complaint entity type in the NYPD-Complaints schema.

  1. Select the Report (KCPD-Crime) item type in the list, then click Create mapping in the right-hand pane. This shows the list of item types to which the Report item type can be mapped.

  2. Select the Complaint item type from the NYPD-Complaints schema, then click Create mapping. You will see all the property types of the Complaint type in the NYPD-Complaints schema, with options available to choose how they should be populated when mapping from a KCPD-Crime Report record.


    KCPD Report to NYPD Complaint unconfigured mapping

  3. In the example below, the property types of the Report (KCPD-Crime) type are mapped to the property types of the Complaint (NYPD-Complaints) according to the following table.

    Report (KCPD-Crime)

    Complaint (NYPD-Complaints)

    Report Number

    Complaint Number

    From Date

    Complaint Start Date

    To Date

    Complaint End Date

    From Time

    Complaint Start Time

    To Time

    Complaint End Time

    Offense Description

    Offence Description

    Offense

    Classification Description

    Report Date

    Date Reported


    KCPD Report to NYPD Complaint mapping

    There is no comparable property type in the Report (KCPD-Crime) type for the following Complaint (NYPD-Complaints) property types:

    • Crime Status

    • Jurisdiction Code

    • Jurisdiction Description

    • Offence Classification Code

    • Level Of Offence

    • Internal Classification Code

    • Location Of Occurrence

    As a result, these types are left unmapped. The properties of Complaints records that are converted from Report records will not be populated.

  4. When you are satisfied with all the property type mappings, confirm the mapping by clicking OK. You should see in the list of types that Report (KCPD-Crime) has been mapped to Complaint (NYPD-Complaints).


    Updated list of types

Location

Following the same process, the Location type from the KCPD-Crime schema can be mapped to the Location type in the NYPD-Complaints schema.

The Coordinates property type of Location (KCPD-Crime) is automatically mapped to the Coordinates property type of Location (NYPD-Complaints). The image shows an example configuration that you could use.


KCPD location to NYPD location mapping

You can see that the Borough Name properties of NYPD-Complaints Locations will be populated from the value of the City properties of KCPD-Crime Location records. These property types are not an exact match for one another, but this mapping at least makes it clear when Locations are in Kansas City rather than New York City, in case Coordinates are not provided.

You can go further and ensure the Borough Name property is always populated in converted Locations by setting a default value that will be used if the source KCPD-Crime Location record does not contain a value for the City property. To do this:

  1. Click the button highlighted to the right of the Borough Name configuration shown below.


    Select default value button

  2. Enter a default value to use for the Borough Name property if a source KCPD-Crime Location record has no City value. For example, "Kansas City".

  3. Click OK.

The mapping of Address to Premises Description does not seem like a perfect match either. But the Address of a Location might be too important not to have, and the Premises Description is a suitable target property in which to store it.

Again, when you are happy with the mapping configuration for Location records, click OK to confirm the mapping.

Person

You can follow the same process to create a mapping from the Person (KCPD-Crime) type to the Person (NYPD-Complaints) type.

The Race and Sex property type mappings are generated automatically, so the only property type left is Age Group. You can map the values of the Age property type from the Person (KCPD-Crime) type, as shown below.


Age property mapping

The Age property types of the source type and the target type are both SUGGESTED_FROM types, but they have different suggested values. The source property type, from the KCPD-Crime schema, has suggested values: <18, 19, 20, 21, ..., 64, and 65+; whereas the target property type, from the NYPD-Complaints schema, has suggested values: <18, 18-24, 25-44, 45-64, and 65+.

The <18 and 65+ values are automatically mapped to one another. For the remaining target values (18-24, 25-44, and 45-64), you must choose which source values should map to them.

You have the option to select a single value of the source property type from the dropdown, but that wouldn't make much sense. The source property values 18, 19, 20, 21, 22, 23, and 24 should all map to the 18-24 target value. To do this, click the button to the right of the dropdown menu beneath 18-24, highlighted below.


Select multiple possible values

Then, select all the appropriate values as shown below, and select a source value to use when the conversion is applied in reverse during any seeded searches.


Select multiple possible values and the reverse value

Located At

The Located At (KCPD-Crime) link type can be mapped to the Located At (NYPD-Complaints) link type by following the same process:

  1. Select Located At (KCPD-Crime) in the list of types, then click Create mapping in the right-hand pane.

  2. Select Located At from the NYPD-Complaints link types, then click Create mapping.

  3. There are no property types to map, so just add a description if you wish.

  4. Confirm the mapping by clicking OK.

Suspect Of

Map Suspect Of (KCPD-Crime) to Suspect Of (NYPD-Complaints) in the same way as Located At.

Victim Of

Map Victim Of (KCPD-Crime) to Victim Of (NYPD-Complaints) in the same way as Located At.

Testing the item type mappings

When you have defined the item type mappings, you should see an updated list of types like the example shown below.


Configured item type mappings

The Arrested, Charged, and Complicit In link types are left unmapped, because there are no suitable target link types in the existing NYPD-Complaints schema. i2 Analyze will recognize that their end types have been mapped, and allow the NYPD-Complaints schema's Person and Complaint types to be connected by these links.

To test the item type mappings by previewing the external searches provided by the NYPD and KCPD connectors:

  1. Click Apply in the top-right. This applies the mappings to the test environment that is available through the Admin Console. (It does not apply the mappings to the live server.)

  2. Click Preview services to open a preview of how the services would behave with the mappings you have configured. Notice how the KCPD Connector's Get All service now returns item types from the NYPD-Complaints schema.

  3. Go back and make any changes to the mappings, repeating steps 1 and 2 until you are satisfied with the configuration.

Applying the item type mappings to the i2 Analyze server

To apply the mapping configuration you have created on the i2 Analyze server for all users, see Applying the mapping configuration to the i2 Analyze server.

The result

In Analyst's Notebook, use some of the services provided by the two connectors and copy some results from each connector to your chart. Notice how there are now no duplicate item types.

For example, compare the chart below to the one at the beginning of this walkthrough. You can see that all of the records have types from the NYPD-Complaints schema, except for the unmapped Arrested and Charged links in the top-right corner.


NYPD and KCPD mapped records