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
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
- Create an object type attribute of the type object reference and configure it according to your data model reflect on the following;
- Which other object type is referenced
- What is the cardinality (at most one, at least one, zero to many etc)
- 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
The attribute configuration in Insight of License
The attribute mapping in the Import Configuration
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.
Importing multiple values into an Object Attribute Type (multiple referenced objects) requires the Attribute's maximum Cardinality to be > 1.
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 row | ColumnName | ColumnCity | Zip Code |
| Data row | ACME studios | Stockholm | 12345 |
| Data row | Rockets "r" us | Stockholm | 54321 |
The Insight Attribute Configuration
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 |
|---|---|---|---|
| Name | String | Stockholm | Stockholm |
| Zip Code | String | 12345 | 54321 |
The import configuration for the Office object type
This shows the result we want to have in Insight after the import in the Company object type
Company | Type | Company 1 | Company 2 |
|---|---|---|---|
| Name | String | ACME studios | Rockets "r" us |
| Office | Object reference (to office) | Office 1 | Office 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
|
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
A sample of the result
There is also a video available showing an example of how to set this up: