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:
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.
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 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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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:
Select Located At (ERI-Reports) in the list of types, then click Create mapping in the right-hand pane.
Select Located At from the KCPD-Crime schema types, then click Create mapping.
There are no property types to map, so just add a description.
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.
To test the item type mappings by previewing the external searches provided by the KCPD and ERI connectors:
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.
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.
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 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.
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.
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.
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.
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.
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.
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
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.
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.
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:
Click the button highlighted to the right of the Borough Name configuration shown below.
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".
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.
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.
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.
Located At
The Located At (KCPD-Crime) link type can be mapped to the Located At (InfoStore) link type by following the same process:
Select Located At (KCPD-Crime) in the list of types, then click Create mapping in the right-hand pane.
Select Located At from the Information Store link types, then click Create mapping.
There are no properties to map, so just add a description if you wish.
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.
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:
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.)
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.
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 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.
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.
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.
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.