2. Create object type and attribute mapping

Still need help?

The Atlassian Community is here for you.

Ask the community

Once your base import configuration is created, you need to map your data to object types and their attributes. You might not need to create full mappings if you've chosen to create a predefined structure and configuration, but this page will help you to review and edit them, if needed.

View your import configuration

Just to make it easier to see where you are, here's a sample import configuration without mappings created (it's invalid because it doesn't have any object type mappings).

Create object type mapping

To create object type mapping:

  1. When viewing your import configuration, click Create object type mapping.
  2. Specify the required fields.
  3. Remember that every object type mapping imports your data into a single object type. If you have more object types, you'll create more object type mappings on the same import configuration. Before you start adding another object type mappings, complete the attribute mapping, as described below. 
View fields for object type mapping
FieldDescription
Object Type

The Insight object type you want to import your data into. This value can't be changed, you need to create a new object type mapping to import into another object type.

Selector

This will differ based on your import type. See your type for details:

Filter data source by IQL

You can filter the data to be imported by IQL before it's actually imported. For example, if you're importing data into Computers object type, you can choose to only import PCs, and not Macs.

Filter on object references

You can't filter based on object references. These are handled separately after the object is created or updated.

Here's a video that explain how to split your import source into different object types using IQL:

Missing Objects

Choose what to do if an object is missing in the data source (but exists in Insight):

  • Update: Update the object with a predefined value to a specified attribute. The Threshold configuration will apply.
  • Delete: Delete the object from Insight. The Threshold configuration will apply.
  • Ignore: Just let the object be.
Missing objects outbound references

Choose what to do if a referenced object (referenced from an existing object in your data source) is missing in the data source. For example, if an import is configured to import the referenced Host and Application object types, and one of them is missing.

  • Remove: The outbound reference to a missing object will be removed.
  • Ignore: Leave the reference as is.

Insight will only consider data from the same import so if you have multiple import configurations, this functionality will not work.

Threshold Type

When objects are missing in the data source, you can specify a threshold for the Update and Delete configurations. This means that Insight will wait with performing these actions until the conditions specified in the threshold are met (days, synchronizations)

Threshold Number

The number of days/synchronizations before performing the actions described above.

Empty Values

Defines what to do if a Data Locator is empty. Should the import remove the attribute value or just ignore it and leave the current value?

This overrides the 'General fields' configuration of your import type for this object mapping.

Defines what to do if a Data Locator is unknown to Insight. This can happen with attribute types like "Status" and "Select". The value can be added as an option, or just ignored.

This overrides the 'General fields' configuration of your import type for this object mapping.

Match Identifier

Case sensitive - Identifier IQL will be built up with STRICT_EQUAL (==) which means that for text attributes, identifiers will be compared respecting case, 'Data Value' will NOT be considered the same as 'data value'.
Case insensitive - Identifier IQL will be built up with EQUAL (=) which means that for text attributes, identifiers will be compared ignoring case, 'Data Value' will be considered the same as 'data value'.

Create attribute mapping

Once your object type mapping is created, you can expand it to see the attribute mapping. Attribute mapping is created for each object type mapping separately, as you'll map data locators from your data source to the object type's attributes in Insight. There needs to be at least one attribute mapping for every object type mapping.

Identifier

Specifies if the attribute should be considered a part of the object identifier. If multiple attributes are used as identifiers, the combined value will be used to identify the object and duplicates. This is used to construct an internal IQL responsible for identifying objects.

For example, if two import attributes are configured for Insight attributes First Name and Last Name, and specified as identifiers, the following IQL will be used to identify objects in Insight:

"First Name" == <first name value from source> AND "Last Name" == <last name value from source>

All attributes can be identifiers. But, for best performance, try to use the default attribute types as much as you can. For example, if using "User" attribute as identifier, we will have to query the Jira API to find users from the data source for the configured data locator. This means that Jira might be a bottle neck in this case if you have a large User directory. Try in this case to add another attribute for the user key (Default / Text) and the import will be much faster.

Data locator

Every import type needs to provide data locators. It's what Insight recognizes as a category that holds your data. For example, in CSV import, all columns are data locators.

Insight attribute

The Insight attribute to which you want to map the data locator, and import its data.

Object mapping (IQL)

Only used for Insight attributes of type Object (references between objects).

In this case, you need to provide an IQL to fetch the objects to set, depending on the data provided by the Data Locator. In the examples that follows, Name is a reference to the value in Insight that the referenced object has, in the attribute Name.

You can use place holders in the IQL like:

  • For single attributes (max cardinality equals 1) the IQL with the placeholder could look like this:

    Name = ${DATA LOCATOR}
  • For multiple attributes (max cardinality larger then 1) the IQL with the placeholder could look like this:

    Name IN (${DATA LOCATOR${0}})

    The "0" (zero) stands for all values, and 1 for the first value, 2 for the second value and so on.

For more info, see Understanding import concepts.

Description

Description for the attribute mapping, just for convenience.

Other configuration

You can access other configuration by clicking the cog icon next to your attribute mapping.

Concatenator

When joining multiple data locators into one Insight attribute, this works as the default concatenator.

Regular expression

You can use regular expressions to edit the value from the import source.

For the regular expression we use Java syntax https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html. If the regular expression does not find any match the attribute is left empty. It is possible to extract from the value given by the Data Locator by making what you wish to extract the first group in the regular expression, for example using the regular expression "(\w*)\W" (quotation marks excluded) on the value "Blue Whale" yields "Blue" to the corresponding attribute. If there is no group present and the regex finds a match the whole value is given.

Some examples:

Purpose

Pattern

Example

Validate that input contains at least one digit\d"foo 123 bar" is returned as is but "foo bar" gives empty attribute value
Extract first digit(\d)"foo 123 bar" gives 1 but "foobar" gives empty attribute value
Extract only first word of text(\w*)\W

"Blue whale" becomes "Blue"

Shorten number to show only two decimals(\d*\.\d\d)12.3456 becomes 12.34

Next steps

When you're ready with your mappings, go to 3. Inspect your import configuration.

Last modified on Feb 2, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.