Converting records between types

A deployment of i2 Analyze that defines a large number of item types across several schemas can become confusing for administrators and users, and might even compromise the utility of the platform. To reduce the number of types in the system, and to enable richer analysis, i2 Analyze supports the dynamic conversion of records from one type to another.

In a deployment of i2 Analyze that includes several schemas, and especially one that features connector and gateway schemas from third parties, there can be multiple item types with similar names or purposes. For example, two connector or gateway schemas might independently define similar "Person" item types, which might in turn be slightly different from a "Person" type defined in the Information Store schema.

This kind of arrangement can have a number of consequences:

  • The existence of several item types with the same or similar names can be confusing for administrators and for users, who see records on their charts and item types in their palettes that look the same, but are not.
  • By the same token, the analytical tools in i2 Analyze and i2 Analyst's Notebook Premium do not consider records with similar-looking types to be equivalent for the purposes of comparison and other functions.
  • Only records that have types from the Information Store schema can be uploaded to the Information Store.

To address these problems, the i2 Connect gateway provides a dynamic type conversion service. At startup, the gateway builds a catalog of all the item types in all the schemas in the deployment. You can then create mappings from one item type to another, in the following combinations:

  • Connector schema type to Information Store schema type
  • Connector schema type to gateway schema type
  • Gateway schema type to Information Store schema type
  • Gateway schema type to gateway schema type (in a different gateway schema)


Type conversion mappings describe how the property values of source records that have a particular item type become the property values of target records that have a different item type.

For example, a gateway schema might define an entity type named "Person", with property types including "Forename" and "Surname". In the same deployment, the Information Store might also define an entity type named "Person", with property types including "First Name" and "Family Name". Provided that the property types in question have compatible logical types, you can create a mapping to change the type of any record with the gateway type so that it becomes a record with the Information Store type.

The effect of this type conversion mapping is that any record that would otherwise appear in search results or on the chart surface with the gateway type instead appears with the Information Store type. As a result, it can be compared directly with existing records in the Information Store, and can itself be uploaded to the Information Store if the user requires it.

Note: It is not mandatory to create mappings between item types. By default, records from connectors are copied to users' charts with their assigned entity or link types, without modification.

To create type conversion mappings, you use the i2 Analyze Server Admin Console.

  1. In a web browser, navigate to the URI of a i2 Analyze development environment, but append /admin.
    For example: http://host_name:9082/opal/admin.

    When you log in as a user with administrator privileges, the i2 Analyze Server Admin Console appears.

  2. On the left of the user interface, select the i2 Analyze Type Conversion app.

    In the main panel, the app displays all the item types from all the connector and gateway schemas in this deployment of i2 Analyze. (Item types from an Information Store schema cannot be source types in type conversion mappings.) For each type in the list, you can create a mapping to a different type.

  3. Select a source item type, and click Create mapping to display the Convert records dialog.

    This dialog displays all the item types from all the gateway schemas and any Information Store schema in this deployment of i2 Analyze. (Item types from connector schemas cannot be target types in type conversion mappings.)

  4. Select a target type for your mapping, and click Create mapping to display the dialog with the same name.

The Create mapping dialog displays a list of the property types of the target item type. For each property type, you can elect to provide no mapping, or to say that a property with this type is to be set from a source property with a specified type, or that a property with this type is always to be set to a fixed value.

  1. Configure the property type mappings as you see fit, and then click OK to create the item type mapping.

    If there are problems with any of the mappings that you create, the app displays inline warning and error messages.

As you develop your type conversion mappings, you can preview their effects on the results that users see when they query external data sources by temporarily applying them to the development server.

  1. Click Apply to apply all the current type conversion mappings to the server.
  2. Click Preview services to display the same Services dialog that users see when they query external data sources.
  3. Select and run some of the queries.
    The descriptions and results of the queries now reflect the mapping that you created. Any references to the source types in your mappings are replaced with their target types.

This approach to previewing the effect of your mappings is not suitable for a production environment, where you must instead deploy a type conversion mapping configuration file to your i2 Analyze servers.

  1. When you are satisfied with the mappings, click Export to create a configuration file named mapping-configuration.json.
  2. Save the configuration file to the configuration\fragments\common\WEB-INF\classes folder of the i2 Analyze deployment toolkit.
  3. Redeploy i2 Analyze to update the application with this change to its configuration. In a command prompt, navigate to the toolkit\scripts directory and run the following commands:
    setup -t stopLiberty
setup -t deployLiberty
setup -t startLiberty
  4. Finally, verify that the changes that you made in the development environment behave correctly in the production environment.