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, select 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 Assets 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 AQL

You can filter the data to be imported by AQL 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 AQL:

Missing objects

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

  • Update: Update the object with a predefined value to a specified attribute. The Threshold configuration will apply.
  • Delete: Delete the object from Assets. 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.

Assets 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 Assets will wait with performing these actions until the conditions specified in the threshold are met (days or synchronizations). 

When you set the Threshold type to Synchronizations and the Threshold number to 1, missing objects will only be removed starting from the second synchronization. Similarly, if you set the Threshold number to 2, missing objects will be removed from the third synchronization onwards.

Threshold number

The number of days or synchronizations before performing the actions described above. If you want to remove missing objects from the first synchronization onwards, set the Threshold number to 0.

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 Assets. 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 AQL 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 AQL 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 Assets. 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 AQL responsible for identifying objects.

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

"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.

If you are importing objects from a CSV file into Assets, you must identify the objects by the attribute that is assigned as a label, not their name or key. The object key is generated automatically when an object is created manually or via import. Even if the object key is present in the source file (say CSV or JSON), a new object and its key will be generated instead of using the one in the source file, especially if the object key is the identifier. This could result in multiple duplicates.

Data locator

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

Assets attribute

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

Object mapping (AQL)

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

In this case, you need to provide an AQL 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 Assets that the referenced object has, in the attribute Name.

You can use place holders in the AQL like:

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

    Name = ${DATA LOCATOR}
  • For multiple attributes (max cardinality larger then 1) the AQL 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 selecting the cog icon next to your attribute mapping.

Concatenator

When joining multiple data locators into one Assets 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 Oct 7, 2022

Was this helpful?

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