Get started with Jira Service Management for admins
Your first stop for learning how to get started with Jira Service Management.
Creating an import structure 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 creating an import structure 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 IT Asset Management (ITAM) process.
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.
Understanding imports
Importing is a way to bring outside data into Assets and convert it into Assets object types, objects, attributes and references.
Importing is the preferred way to bring data into Assets because it’s quicker, easier, and more dynamic than creating data using the interface.
To import data into Assets, we need the following three things:
Data is raw information that we will pull into Assets. This data can be in the form of a CSV or JSON file, or it could be directly from a third-party app or provider.
Structure is the object types, attributes, and references in Assets that provide a framework for our data. Depending on how we want to manage our import, we may want to use a structure that we’ve already manually created, or we might want to let Assets create the object types and attributes entirely by itself.
Mapping is a way of connecting our data and our structure by linking specific pieces of information in our data source with specific objects or values in our structure. Mapping also ensures this data fits in the correct place, and makes sure this information is normalized and accurate.
There are three levels of mapping in Assets - import mapping, object type mapping, and attribute type mapping.
Each nests inside the others - so import mapping is a group of object mappings, and each of those object mappings can contain more than one attribute mapping.
Import mapping contains general information about how the raw data is configured, such as how it’s encoded and how it can be broken up into objects and object types.
Object type mapping contains more specific information about how to create objects and object types from the mapping.
Attribute type mapping contains fine details about how to convert the raw data into attributes for the new objects.
Let’s look at how all of this works with IT Asset Management (ITAM).
Following the previous sections in this guide, we’ve created an object schema and attributes to hold our information. That will be our structure. Now we will bring our data into Assets and map it to create objects and attributes.
We’ll be getting our data from two different data sources - a model data source and and assets data source. Both of these data sources will be in CSV format.
Understanding information architecture when importing
One of the key concepts in Assets is information architecture, which is understanding and developing the best ways to organise your data. In Assets, the information architecture is how you built object types and attributes to hold your data.
The same general rules that you saw earlier when creating your object types also apply to creating import structures. Let’s review them:
Your import structure is the right size. Your import structure fits the data that you are importing. You have one object type mapping for each object you want to create, and one attribute type mapping for each attribute within that object.
Your import structure is unique. Your import structure doesn’t replicate mappings that are found in another import structure. If you want to create multiple different object types from a single set of potential objects, you should try to create them all at once using child object mapping.
Your import structure is extensible. Your object structure is designed in such a way that it can be modified if the data changes, or even if the schema changes! We recommend creating full-fledged objects when importing using the AQL field in the Attribute mapping screen.
As we bring in our data, we want to make sure that we are bringing in the model and the assets data separately, and treating them as unique. There’s a couple of reasons for this:
We are connecting each data source into a different location in our object schema. The assets of existing stock will populate our Hardware assets object type and it’s children, while our model of potential IT assets will populate our Model object type and it’s children. Because each data set has a different destination, we will use a unique mapping for each.
We also want to process each data set separately. Our Model data can be imported directly, but our Hardware assets data we want to normalise by comparing to the results of our previous imports. We want to do this so we can check for missing assets, extra assets we weren’t expecting, or any anomalies between the expected and actual stock levels.
Finally, our model and assets data sets won’t necessarily be updated a the same time. By keeping them separate, we can make sure our assets is current while our model is less vital.
Understanding import structures
An import structure is a recipe that tells Assets how to run an import. This recipe include all of the details above - where Assets can find the data, where Assets will build the structure for the data, and how Assets can break down the data into little pieces and use the mapping to put those pieces in the correct place.
Assets has the ability to manage and run multiple imports of different kinds, and overlay information from different sources (or from the same source!) to create an accurate and up-to-date single source of truth.
There are different kinds of import structures, correlating to the different sources of data that Assets can accept. Currently, there are four main types of import structure:
CSV
JSON
Assets Discovery
External imports
You can also use our REST API framework to import data from external sources. Learn more about importing using the Imports REST API guide in our developer documentation section.
Formatting CSV data
We don’t have to worry about formatting our data today because we’re going to use the sample data provided, but in other circumstances this might be very important. If there is a syntax error in your CSV or JSON data file, your import may produce unexpected results or not run.
Here is some information about data formatting for CSV that you might need to know in the future.
You can use any of the following formats: UTF-8 (default), UTF-16, ISO-8859-1, ISO-8859-15, Windows-1250, Windows 1252.
The CSV file must have a header as it is used to create the data locators for the imports.
The CSV file must include a single-character delimiter. The default delimiter is, naturally, the comma. You can select a custom delimiter in the Delimiter field when you create an import configuration. To include a delimiter character, place the value between double quotes. To include a delimiter or a double quote character, place each value between double quotes. You can also enter “\t” to use a tab-delimiter.
To divide multiple values (for the Assets attributes with multiple cardinalities), you can use “||” (2 pipe characters) within the CSV file.
If you wish to join multiple values into one Assets attribute, you can use a concatenator in the CSV file. The default is a dash symbol “-”. If the data is concatenated with a space, you can enter “\s” in the Concatenation field when creating an import configuration.
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.
If you are importing Jira users or groups into Assets, you must identify the users or groups by their IDs, not their Name(s).
If you are importing URLs into Assets they must begin with with http:// or https:// to be converted into the URL attribute type. If the http:// or https:// prefix is not included, they will be imported as the String attribute type. Learn more about attribute types.
If you are importing CSV data from a Google Sheets link, the URL you use must be edited before it will work properly. Remove /edit#gid=0 from the ending of the URL and replace it with /export?format=csv.
Creating data sets
Before we can start importing data into Assets, we will need a data source. A data source could be a static data file, such as an uploaded CSV or JSON, or it could be hosted on the web.
For this tutorial we will use two separate data sources - model and assets. The model will hold information about all of the possible IT assets that we might encounter, while the assets will list only those inventory items that are currently in the system. By separating between the model and the assets, we will be able to import the model from one location - such as a vendor list, and sync it with our current inventory of assets..
Here’s some sample CSV data for our model listing information like models and technical specifications. Our model currently 40 objects - 10 different laptop models, 10 different phone models, 10 different server models, and 10 different printer models.
Each model contains details specifying the Category, the Model, the Unit Price and the Description. These details in the data file will be mapped to the appropriate attributes in the Models object type.
Let’s copy this data into a text file and give it the name models.csv, since it describes our current model of possible laptops.
Make sure to save each CSV files in the UTF-8 format. Although Assets can accept data in a multitude of formats, UFT-8 is the most commonly used format for CSV files.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Model Name,Category,Unit Price,Description
iPhone 12,Phone,999,Apple iPhone 12 64GB
iPhone 11,Phone,799,Apple iPhone 11 64GB
Galaxy S21,Phone,999,Samsung Galaxy S21 128GB
Galaxy S20,Phone,899,Samsung Galaxy S20 128GB
Dell XPS 15,Laptop,2000,Dell XPS 15 9500 15.6" Laptop
HP Spectre x360,Laptop,1500,HP Spectre x360 13.3" Laptop
Lenovo ThinkPad X1 Carbon,Laptop,1900,Lenovo ThinkPad X1 Carbon 14" Laptop
MacBook Pro 16,Laptop,2400,Apple MacBook Pro 16" Laptop
Dell PowerEdge R640,Server,5000,Dell PowerEdge R640 1U Rack Server
HP ProLiant DL380,Server,5500,HP ProLiant DL380 Gen10 2U Rack Server
Lenovo ThinkSystem SR630,Server,6000,Lenovo ThinkSystem SR630 1U Rack Server
HP LaserJet Pro MFP M428fdw,Printer,350,HP LaserJet Pro MFP M428fdw Monochrome Laser Printer
Canon imageCLASS MF743Cdw,Printer,500,Canon imageCLASS MF743Cdw Color Laser Printer
Brother MFC-L2750DW,Printer,250,Brother MFC-L2750DW Monochrome Laser Printer
Epson WorkForce Pro WF-4830,Printer,300,Epson WorkForce Pro WF-4830 All-in-One PrinterNow that we have our model information, let’s do the same thing with our assets. Our assets data file will contain information specific to the actual IT asset we have on hand, such as the serial number, owner, purchase date, and status.
Let’s copy this data into a separate text file and give it the name assets.csv.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Device Type,Serial Number,Model Name,Purchase Date,Owner Group,Status,Asset Tag,PO Number,Asset Status
Phone,SN001,iPhone 12,01/01/2021,HR,Active,AT001,PO001,In Use
Phone,SN002,iPhone 11,01/02/2020,Sales,Active,AT002,PO002,In Use
Phone,SN003,Galaxy S21,03/01/2021,IT,Inactive,AT003,PO003,In Stock
Phone,SN004,Galaxy S20,12/01/2019,Finance,Active,AT004,PO004,In Use
Laptop,SN005,Dell XPS 15,06/01/2020,HR,Active,AT005,PO005,In Use
Laptop,SN006,HP Spectre x360,07/01/2019,Sales,Inactive,AT006,PO006,Disposed
Laptop,SN007,Lenovo ThinkPad X1 Carbon,08/01/2018,IT,Active,AT007,PO007,In Use
Laptop,SN008,MacBook Pro 16,10/01/2020,Finance,Active,AT008,PO008,In Use
Server,SN009,Dell PowerEdge R640,04/01/2018,IT,Active,AT009,PO009,In Use
Server,SN010,HP ProLiant DL380,05/01/2019,IT,Inactive,AT010,PO010,In Stock
Server,SN011,Lenovo ThinkSystem SR630,11/01/2020,IT,Active,AT011,PO011,In Use
Printer,SN012,HP LaserJet Pro MFP M428fdw,02/01/2021,Sales,Active,AT012,PO012,In Use
Printer,SN013,Canon imageCLASS MF743Cdw,05/01/2020,HR,Active,AT013,PO013,In Use
Printer,SN014,Brother MFC-L2750DW,08/01/2019,Finance,Inactive,AT014,PO014,Disposed
Printer,SN015,Epson WorkForce Pro WF-4830,03/01/2021,IT,Active,AT015,PO015,In UseCreating import structures
Now that we have two sets of CSV data, we will create an import structure for each of them. Each import structure will contain the details about how to convert the data into objects and attributes in Assets.
To create each import structure, we’ll be guided through some steps to configure our data and upload the CSV files that we created in the last section.
Let’s name the first import structure models-import. We will upload the file we created in the last section, which we called models.csv.
The second import structure we will name assets-import. We will upload the file we created in the last section, which we called assets.csv.
Because we’ve already created object types and attributes for our model data, we will disable Automatically create object types and attributes for both of these import structures and create the object mapping and attribute mappings from scratch.
For now, we won’t modify any of the default settings for delimiter, encoding, concatenator, empty values, unknown values or date formats.
The following process we will have to do twice, once for model-import and once for assets-import.
To create an Import structure:
From your service project, go to Assets > Object schemas.
Select an Object schema.
Select Schema configuration, then choose the Import tab.
Under the Import tab:
If there is no import structure you will see the message No Import structure created. Click on Be the first to create one.
If an import structure has already been created, click Create import to add a new import structure.
Select CSV import from the options provided.
Next, use the Define import structure screen to configure your import structure. If you are creating an External import you can skip this step.
Name (required) - enter a name for the import configuration.
Description - enter a description for the import configuration.
Drag or drop a file, or Browse (required) - drag and drop or browse for your source data file here.
Automatically create object types and attributes - disabling this option requires you to manually map your data to your schema before importing data. Learn more about manually mapping your data.
More options - modify the default values here to change how Assets will deal with delimiters, encoding, empty or unknown values, concatenation, and date formats.
Delimiter (required) - Select the delimiter used in the file. A delimiter is the character that denotes where one value stops and the next one starts. Only delimiters of one character length are allowed, except for the “Tab” character which is indicated with “\t”. To include a delimiter or a double quote character, place each value between double quotes.
Encoding (required) - Select the encoding used in the CSV file. The default encoding is UFT-8.
Concatenator (required) - if you wish to join multiple values into one Assets attribute, you can use a concatenator. The default is a dash symbol “-”. You can enter “\s” if the data is concatenated with a space.
Empty values - When an object is updated, choose if empty values from the external source should remove the existing value. Select from:
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.
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.
Unknown values (required) - choose if you want to ignore or add empty values.
Date Format - Select a format to convert dates into Assets. Assets will automatically try to find the correct format if none is provided.
Date/Time format - The date/time format to convert dates with time into Assets. Assets will automatically try to find the correct format if none is provided.
Select Create.
The Imports tab should now be populated with your new import structure.
Understanding automatic or manual mapping
When you create a new import structure, you have the option of manually or automatically creating object types and attributes.
If you choose to automatically create object types and attributes, Assets will create a default structure and configuration based on the type of import you have selected and the structure of the data you are importing. For example, when automatically mapping data from a CSV file, Assets will create a new object type with the name of the CSV file, a new object for each row in the file, and create attributes for each object based on the values in the header row of the CSV.
If there is already an object type in your object schema with the same name as the CSV file you are importing, Assets will not create a new object type, but will overwrite the your existing objects and their attributes with the same objects from your data source.
If you choose to create an import manually, the import structure will not automatically create object types and attributes, and it will not automatically map data from the data file into the import. Your import structure will be “empty”, and you will have to map your data into Assets using import mapping, object mapping, and attribute mapping before you can run the import.
Good work!
We’ve now learned about how importing and import structures work, and we’ve created two import structures - one for the data that will become the models and one for the data that will become the assets.
Next, let’s move onto the next section in the guide: Mapping objects and attributes for IT Asset Management (ITAM).
Was this helpful?
Still need help?
The Atlassian Community is here for you.