Adding a connector with a connector schema to an existing deployment with a gateway schema and an Information Store schema

This example scenario demonstrates how to add a new connector with its own connector schema to an i2 Analyze deployment with an existing gateway schema and an Information Store schema. Item types in the connector schema are mapped to item types in the gateway schema, and item types in the gateway schema are mapped to item types in the Information Store schema.

The example also demonstrates how i2 Analyze resolves item type mappings that are chained together. That is, how mapping type A to type B and type B to type C results in an implicit mapping from type A to type C, so that all records of type A are converted to records of type C. It further shows how mapping to item types in the Information Store schema allows converted records to be uploaded to the Information Store.

Setting up the scenario

To follow this example:

  1. Deploy i2 Analyze with the Information Store and the example NYPD connector, as described in the analyze-connect repository.

    Use the NYPD schema as the Information Store schema, and configure the connector to use it.

  2. Add the example KCPD connector to the deployment, but configure this connector to use a gateway schema.

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


KCPD records with gateway schema

Adding a new connector with a connector schema

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

You can now use the services provided by the ERI connector, and copy results from those services to the chart too.


Unmapped KCPD and ERI records

The image uses highlighting and different icons to show how the gateway schema used by the KCPD connector and the connector schema used by the ERI 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:

  • 'Location' entity type

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

  • 'Located At' link type

You can use type conversion mappings to resolve this duplication.

Configuring item type mappings from a connector schema to a gateway schema

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 the list of all item types in the ERI-Reports schema, and that none of them has been mapped.


Unmapped ERI-Reports item types

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

Incident and Report

The Incident entity type in the ERI-Reports schema can be mapped to the Report entity type in the KCPD-Crime schema.

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

  2. Select the Report item type from the KCPD-Crime schema types, then click Create mapping. You will see all the property types of the Report type in the gateway schema, with options to choose how they should be populated when mapping from an ERI-Reports Incident record.


    ERI Incident to KCPD Report unconfigured mapping

  3. In the example below, the property types of the Incident (ERI-Reports) type are mapped to the property types of the Report (KCPD-Crime) according to the following table.

    Incident (ERI-Reports)

    Report (KCPD-Crime)

    Creation Date

    From Date

    Closed Date

    To Date

    Creation Time

    From Time

    Closed Time

    To Time

    Incident Subtype

    Offence Description


    ERI Incident to KCPD Report mapping

    There is no comparable property type in the Incident (ERI-Reports) type for these Report (KCPD-Crime) property types:

    • Report Number

    • Report Date

    • Offense

    • Domestic Violence

    As a result, these types are left unmapped. They will not be populated in Report records that are converted from Incident records.

  4. When you are satisfied with all the property mappings, confirm the mapping by clicking OK. The result is a validation warning message that occurs when a mandatory property of the target type is unmapped, which is the case for the mandatory Report Number property type of the Report (KCPD-Crime) item type. Any Report entity created from an Incident entity using this mapping would not have a Report Number, which would make that Report invalid.


    ERI Incident to KCPD mapping validation error

  5. To provide a Report Number in all circumstances, select the Incident (ERI-Reports) item type in the list, then click Edit mapping in the right-hand pane to update the mapping. In the mandatory Report Number (KCPD-Crime) property type, select the dropdown menu and change the type to Fixed value. Populate the field with a constant value.

  6. After you update the property type mapping, confirm the item type mapping by clicking OK.

Location

Following the same process, you can map the Location type from the ERI-Reports schema to the Location type in the KCPD-Crime schema.

The Address and Coordinates property types of Location (ERI-Reports) are automatically mapped to the Address and Coordinates property types of Location (KCPD-Crime). Below is an example configuration you could use.


ERI Location to KCPD Location mapping

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

Located At

You can map the Located At (ERI-Reports) link type to the Located At (KCPD-Crime) link type by following the same process:

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

  2. Select Located At from the KCPD-Crime schema types, then click Create mapping.

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

  4. Confirm the mapping by clicking OK.

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

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

  1. Click Apply in the top-right. This applies the mappings to the test environment that is available only 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 ERI Connector's "All data" service now returns item types from the KCPD-Crime 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 Premium, use some of the services provided by the 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 very beginning of this walkthrough. You can see that all of the records have types from the KCPD-Crime schema, including the records from the ERI connector. This is because of the mapping configuration that maps the item types in the ERI-Reports schema to the item types in the KCPD-Crime schema.


KCPD and ERI mapped records

Uploading converted records to the Information Store

Mapping connector types to gateway types does not result in records that can be uploaded to the Information Store. The item types of the records are defined in the KCPD-Crime gateway schema, not the Information Store schema. Next, you can define mappings from the gateway schema to the Information Store schema, and see that the records returned from both connectors can then be uploaded to the Information Store.


KCPD and ERI mapped records upload disabled

Configuring item type mappings from a gateway schema to an Information Store schema

In a web browser, go to 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 the 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 Information Store schema.

Report and Complaint

The Report entity type in the KCPD-Crime schema can be mapped to the Complaint entity type in the Information Store 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 Information Store schema, then click Create mapping. You will see all the property types of the Complaint type in the Information Store schema, with options available to choose how they should be populated when mapping from a KCPD-Crime Report record.

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

    Report (KCPD-Crime)

    Complaint (InfoStore)

    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 Information Store Complaint mapping

    There is no comparable property type in the Report (KCPD-Crime) type for the Complaint (InfoStore) 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.

Location

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

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


KCPD Location to Information Store Location mapping

You can see that the Borough Name properties of Information Store 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 for KCPD city

  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 satisfied 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 (InfoStore) 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 Information Store 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, as 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 (InfoStore) 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 Information Store link types, then click Create mapping.

  3. There are no properties 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 (InfoStore) in the same way as Located At.

Victim Of

Map Victim Of (KCPD-Crime) to Victim Of (InfoStore) 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 Information Store schema. i2 Analyze will recognize that their end types have been mapped, and allow the Information Store 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 KCPD and ERI connectors:

  1. Click Apply in the top-right. This applies the mappings to the test environment that is available only 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 and ERI Connector's All data service now return item types from the Information Store 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 Premium, use some of the services provided by the connectors and copy some results from each connector to your chart. Notice how the KCPD and ERI connectors now return records whose item types are defined in the Information Store schema.

The KCPD connector returns records whose item types are defined in the KCPD-Crime schema, which are converted directly to records whose item types are defined in the Information Store schema.

The ERI connector returns records whose item types are defined in the ERI-Reports schema. These types are mapped to item types in the KCPD-Crime schema, which are themselves mapped to item types defined in the Information Store schema. What happens as a result is that the records returned by the ERI connector are converted to records that align with the Information Store schema.

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 Information Store schema, except for the unmapped Complicit In link in the top-left corner.


KCPD and ERI mapped records

Uploading converted records to the Information Store

If you want to upload the selected records to the Information Store, you will notice that the button is now enabled.


KCPD and ERI mapped records upload enabled

Click Upload Records. In the open window, you will see that one of the records - the unmapped Complicit In link in the top-left corner - cannot be uploaded because its item type is not from the Information Store schema.


Upload records

If you want to upload this record, you must configure a mapping for its item type. Otherwise, you can click Upload to upload the aligned records to the Information Store.