• Get started
  • Documentation

Mapping imported data for IT Asset Management (ITAM)

Assets in Jira Service Management is a Premium and Enterprise only feature. Learn more about Assets.

How to use this guide

This chapter of the Assets guide will walk you through mapping objects and attributes for importing in Assets. To get the best results from this chapter, you should have completed the previous chapters:

Each step in this guide will include detailed instructions about how to use Assets in Jira Service Management, and also some tips and best practices about how to get the most out of this powerful feature when using it as part of your team’s ITAM processes.

There are two types of information in this guide:

  • The headers with the blue background will help you get started in Assets. They will provide you with information about each step in the guide, including examples of data and how each feature can be used.

  • The text with the white background will give you a series of steps to help you navigate through Assets, or it will contain detailed information about an Assets concept.

And some notes about the text:

  • Information in bold indicates text that you will find in Assets itself, such as the name of a menu option, a feature you can toggle on and off, or a button.

  • Information in code is text that’s part of our example object schema for IT Asset Management (ITAM).

  • Information in bold italics is a concept or idea that forms an important part of Assets.

Creating an object mapping

In the previous chapter, we completed the first step of importing data into Assets by creating an import mapping.

Now we will complete the next step - object type mapping - to tell Assets how to convert the data into objects in our object schema. We can see that the status of our new import structure is marked as disabled - this is because we don’t have any object mapping in place.

We’ll go back into the import structure that we just created, Models import and create a new object type mapping. We will fill in the field at top:

  • Object type tells Assets which pre-existing object type we will be filling with objects. The dropdown list should already be populated with object types, which Assets has found by reading our data file and identified as an object type. In the future, we can modify how Assets finds object types in our data file by changing the identifier. Today, let’s select Hardware models as the object type.

Below this, we have a set of fields that allow you to pre-process the data coming into Assets. Let’s leave all of these as default, except for Missing objects, which we will go into in a later section. These fields are:

  • Filter data source by AQL allows you to filter the incoming objects by an AQL query. For example, if you had a large list of servers and laptops mixed up in a data file, you could use an AQL query here to assign incoming objects to a child object type.

  • Identifier case matching lets you choose if the data is case-sensitive.

  • Missing objects lets you choose what to do if you are updating your data and an object is missing from the data file. You can choose to remove the missing object from your object schema, ignore it, or modify an attribute in the missing object. For example, if you have a data file of your laptops, you might decide to have Missing objects change the status of your laptop from present to missing if it can’t be found in the data file.

  • Missing objects outbound references lets you choose what to do if all of your objects are present, but some of the objects that are referenced by your data cannot be found. You can choose to remove these missing references, or simply ignore them. This rule only runs if Missing objects, above, runs.

  • Empty values - this setting is particular to the reference, status, and select attribute types, which can hold multiple values in a single attribute. It lets you choose what should happen if your object is expecting values in this reference, status, or select attribute type, but it doesn’t find as many values as it expects. You can choose for Assets to remove the missing values that it doesn’t find in the data, or simply ignore the missing values.

  • Unknown values - this setting is particular to the status and select attribute types. When a status or select attribute is updated, you may choose if new values from the source should be added to the list of Status or Select types. This allows you to dynamically update the options for these fields.

To create a new object mapping:

  1. From your service project, go to Assets > Object schemas.

  2. Select an Object schema.

  3. Select Schema configuration, then choose the Import tab.

  4. Select Edit mapping on your import structure to expand it.

  5. You must create a separate object type mapping for each object type that you wish to create from the data. Select the Create mapping button to create a new object type mapping. In the Create a new object type mapping screen, enter the following information:

    1. Object type - select what object type to create from the data. You must have already created an object type to import the data, as per step (2), above.

    2. Filter data source by IQL - An optional IQL to query the objects fetched from source. If you wish to filter the objects from data, you can accomplish that here.

    3. Identifier case matching - select either:

      1. Case sensitive - Identifiers will be compared respecting case, 'Data Value' will NOT be considered the same as 'data value'.

      2. Case insensitive - Identifiers will be compared ignoring case, 'Data Value' will be considered the same as 'data value'.

    4. Missing objects - select from:

      1. Remove - Only entries from the import will persist as Assets object/s. Any object manually created in Assets will be deleted.

      2. Update - All objects in Assets not present in the import will have an attribute edited.

      3. Ignore - Objects in Assets that are not present in the import won't be removed or updated.

    5. Threshold number - the threshold number is the number of times that missing objects from the import source will be ignored before the rule selected in the Missing objects configuration field, above, is applied. This is a safety feature to avoid deleting objects immediately when they are not discovered in the import source data.

    6. Missing objects outbound references - this setting will appear only if you have selected Update or Ignore from Missing objects, above. Select from:

      1. Remove - Only outbound references from the import will persist as Assets references. Any outbound references manually created in Assets will be deleted.

      2. Ignore - Outbound references in Assets that aren’t found in the import won't be removed or updated.

    7. Empty values - When an object is updated, choose if empty values from the external source should remove the existing value. Select from:

      1. Use default - use the value specified in the “Define import structure” screen for this object type.

      2. Remove - remove the current value. If the attribute is a status, select, or reference type attribute with more than one value, all of the values will be removed.

      3. Ignore - keep the current value for this object type. If the attribute is a status, select, or reference type attribute with more than one value, all of the values will be kept.

    8. Unknown values - When an object is updated, should unknown values from the external source be added to the Assets attribute configuration. Select from:

      1. Use default - use the default value.

      2. Add - add the two values together.

      3. Ignore - keep the current value.

  6. Select Create.

Selecting an identifier for an attribute mapping

Now that we’ve created an object mapping, we can see that Hardware models is listed under Mapping.

We’ll also notice that it’s currently marked as disabled, the same as it’s parent import structure Models import.

This is because we’ve decided to manually map our data, so we don’t currently have an identifier assigned for this attribute mapping. The identifier lets Assets know which of the attributes in our object type is going to be unique for each object. This attribute is usually a name, but can also be a serial number, storage ID, or anything else you desire.

Go into your Models import import, and select Edit mapping under Hardware models and then Edit attributes mapping.

Now we’re looking at the attribute mapping for Hardware models - the rules that define how Assets builds attributes from your data. Each row in this table is a different attribute of the object type specified above, in this case, Hardware models.

Let’s select an identifier. We’ll select something unique - the Model Name from the data file. In the of Hardware models, the Model Name is unique and makes a good key. In the case of an inventory list, on the other hand, the model wouldn’t make a good key because there might be multiple instances of the same model, and a unique Serial Number would be better.

We’ll set the Data source to Model Name and our Destination attribute to Name. We notice that Name is marked with a label icon, meaning that the name is also the attribute that will appear in the title bar when we’re viewing the object in the object view.

To select an identifier for your object mapping:

  1. From your service project, go to Assets > Object schemas.

  2. Select an Object schema.

  3. Select Configure, then choose the Import tab.

  4. In the Import tab, select on Edit mapping on your import structure to view the object type mappings.

  5. Select Edit attributes mapping to view the attribute type mappings.

    1. Select a Data source field. If you are selecting a data source field that is to be your identifier, you should select a value that is unique for every object.

    2. Select a Destination attribute. The destination attribute is the attribute where the data source field will be mapped.

    3. Ensure that the Identifier checkbox is selected.

Creating an attribute mapping

Now that we’ve selected a unique identifier for our objects, we can populate the Hardware models objects with attributes pulled from the data source.

Let’s create the following attribute mappings. For each row we will add a data source field and a destination attribute. For the attribute mappings where we are creating references from the text found in the CSV, we must also add an AQL statement to create the reference.

Go into our Models import import structure, and select Edit mapping under Hardware models and then Edit attributes mapping.

  1. Data source field: Category | Destination attribute : Category

  2. Data source field: Model | Destination attribute : Model

  3. Data source field: Unit Price | Destination attribute: Unit Price

  4. Data source field: Description | Destination attribute: Product information

Don’t forget to click Add after each attribute mapping!

To create a new attribute mapping:

  1. From your service project, go to Assets > Object schemas.

  2. Select an Object schema.

  3. Select Configure, then choose the Import tab.

  4. In the Import tab, select on Edit mapping on your import structure to view the object type mappings.

  5. Select Edit attributes mapping to view the attribute type mappings.

  6. Every object imported into Assets will require at least one piece of information - the data source field that lets Assets know where to find objects in the data source. Learn more about the data source field.

    1. Select a Data source field. The data source field specifies the location of the objects in the data file. Your attribute mapping will be disabled until you supply a data source field for each mapped attribute.

    2. Select a Destination attribute to map to the data source field.

    3. Optionally, you can modify the default settings for this attribute mapping:

      1. AQL - enter an AQL statement here to create references from data.

      2. Concatenator - enter an alternative concatenator here that applies only to this attribute mapping.

      3. Regular expression - enter a regular expression here (regex) that applies only to this attribute mapping.

      4. Base 64 - enter an alternate Base 64 value here.

  7. Select one of the attributes as an identifier. An identifier uniquely identifies each object, and will become that object’s new label when it is created. You must have exactly one identifier to run your import. The identifier is also important when you are updating data - any object with the same identifier in the destination schema will be updated, while objects with identifiers not found in the destination schema will be created.

  8. Click Add, at right.

Enabling an attribute mapping

<