This documentation is for Insight for Server/Data Center only.

One key feature is to be able to reference other object(s) when importing data. The object(s) that references should be created to may or may not be imported alongside the current object. This page will describe the way Insight is designed regarding the import part of the object type reference. 

The Three Mappings

The three mappings of an import

As discussed earlier the import is designed with three mapping types; the first to map the external data source (named Jira Env in the image), the second to map the data to one or more object types (Application in the image) and the last to map each data cell to an Insight attribute (License SEN Number in the image). The import configuration is just these mappings all configuration of your structured data in Insight is handled as usual by Insight.

Step by step how to configure an object type mapping

  1. Create an object type attribute of the type object reference and configure it according to your data model reflect on the following;
    1. Which other object type is referenced
    2. What is the cardinality (at most one, at least one, zero to many etc)
  2. Go to the import configuration and create the mapping


Creating the object type reference mapping

Understanding what is referenced

When an Insight attribute of type Object Reference is chosen in the attribute mapping part of an Import the field  "Object mapping (IQL)" will be available. The field is a text area where you enter the IQL based on the referenced object type. It is important to understand that it is the object type (or types if include children is configured to be true) that is referenced that is the key here. See the following example:

The attribute configuration in Insight of Application

Attribute configuration

The attribute configuration in Insight of License

License Attribute Configuration

The attribute mapping in the Import Configuration

Import Attribute Mapping

Note how the Object Mapping in the Import Configurations is referencing the attribute SEN Number as found on the License Object Type even though the configuration is of the Application Object Type.

Creating the Object Mapping (IQL)

The object mapping IQL can be created using all available IQL functions with one addition, the placeholders. Each configured data locator can be used as a placeholder in the IQL. In the example above the data locator License SEN Number is configured in the Data Locator column which will make the placeholder ${License SEN Number} available in the Object Mapping (IQL). 

Read more about placeholders.

Some import modules supply multiple values from a single data locator. If that is the case the placeholder ${Data Locator${i}} can be used. Where Data Locator is the mapped locator as described above and i is the index of the data found by the locator. The most common configuration is ${Data Locator${0}} which renders 2 pipes (||) separated list of all values provided by the data locator e.g.

Attribute IN ( ${Locator${0}} )

It is possible to use ${Data Locator${1}} to get hold of only the first value as well.

Please refer to each import modules documentation to determine if a data locator provides a single or multi value.


When data is imported based on the configuration each data entry (e.g. a row in a CSV file) will have it's value(as identified by the data locator) replaced in the IQL.




Example 

Given the following CSV file (The pink color is added to illustrate meta values. They are not included in the data file) example1.csv

File1 - Office 

Meta information


CSV header rowColumnNameColumnCityZip Code
Data rowACME studiosStockholm12345
Data rowRockets "r" usStockholm54321

The Insight Attribute Configuration

Example 1 Insight Attributes

The same file (File 1) is mapped to two object types Office and Company


This illustrate what we want the data in Insight to be after the import of the file in the Office object type.

Office

Type

Office 1

Office 2

NameStringStockholmStockholm
Zip CodeString1234554321

The import configuration for the Office object type

Example1 Import Configuration Office

This shows the result we want to have in Insight after the import in the Company object type

Company

Type

Company 1

Company 2

NameStringACME studiosRockets "r" us
OfficeObject reference (to office)Office 1Office 2

In order to create the reference to "Object 1" and "Object 2" we have to reference the objects based on multiple attributes in the form of an IQL. The IQL will  like 

Name = ${ColumnCity} AND "Zip Code" = ${Zip Code}

Where the placeholders are referenced from the data locators as specified in the configuration. The IQL will be configured as the attribute configuration for the Companys Office attribute configuration i.e. it will only be available if the attribute type is of object type. 


The import configuration for the Company object type

Example1 Import Configuration Company

A sample of the result

Example1 Result

There is also a video available showing an example of how to set this up: