Export and import asset data
20 min
Advanced
By the end of this lesson, you’ll be able to:
- Export objects to CSV
- Create an import configuration
- Automatically and manually map import data to object types and attributes
- Manually map import data to object types and attributes
- Map import data to referenced object types
- Configure an import to process missing objects
Manage asset data efficiently
Exporting and importing Assets data from Jira Service Management is crucial for maintaining accurate and up-to-date asset information. Exporting allows you to back up your data or analyze it outside of Jira by converting it into a CSV file. On the other hand, importing facilitates the easy addition of large datasets or updates to existing asset information by bringing in data from various sources like CSV files or external databases. This process ensures that your asset data remains comprehensive and current.
Export data from assets
Assets’ export to CSV feature lets you export objects to a CSV file. The export can be performed from the object type view.
To export data from Assets:
- Navigate to Assets.
- Select the object schema where the objects are located.
- Select the object type where the objects are located. Optionally, you can filter the objects using the object type filter search or advanced search.
- Select the List view icon.
- Select Bulk actions and select Export objects from the dropdown.
- From the popup window, configure the settings for the export. The options include Delimiter, Encoding, and Format. The format options are user-friendly or data consistent.
- Select Export. The objects will be exported as a CSV file including all available columns. There is no option to select columns.
Import data into Assets
Importing populates schemas with data from external sources, automatically converting it into object types, objects, attributes, and references. Importing data into Assets from other systems can be highly beneficial and helps keep asset information current.
👉For example: An Assets import can provide an agent with the information needed to resolve problems quickly, such as customer data from an ERP system that gives an agent access to contact information and service agreements. Assets' flexible importing system enables it to acquire data from many external sources.
Configure imports
The import must first be configured before data can be imported into Assets. A separate import configuration and mapping must be created for each import type or data source, and optionally, a schedule can be created for the import to run automatically. Assets can store and run multiple import configurations. There are two main components to configuring imports:
- Source configuration: describes where to find the data and how it's formatted.
- Data mapping: describes how the data will be mapped to the object schema.
👇Click the boxes to expand to learn about each step.
Jira administrators and Assets managers can configure imports in Assets.
Import types
CSV, JSON, and Asset Discovery import types are available in Assets.
👇 Click each tab to learn more about their differences.
- The simplest method of importing data
- Import from Excel files saved as CSV
- Eliminates Excel files stored on shared disks
Additional apps available for free on the Atlassian Marketplace can extend import types. Integrations are available for many popular systems, including AWS, ServiceNow, Tempo, and others. These are installed as separate apps in Jira Service Management and are available for free.
Prepare data for import
If your data is being imported manually, it must be formatted appropriately so Assets can correctly interpret it.
Manual imports use CSV files, JSON files, or Assets Discovery packages to provide data to Assets. Each has specific formatting specifications.
👇Click to expand and learn more about the requirements for preparing different file types.
👇Watch this video to see how to import a JSON file with automatic data mapping.
Create an import structure
Each import type (Discovery, CSV, JSON, External) requires its own configuration. It can store and execute multiple imports of different types. Imports are configured per schema.
When creating the import structure, you select the import type then define general settings for the import. This is basic information that pertains to all import types.
👇Click the icons below to explore these configuration fields.
In the same page, we also configure settings unique to the selected import type.
- You need to provide a URL and credentials for external systems that require a connection.
- For imports like CSV and JSON, you need to point to the import file or web address, and other settings such as encoding and delimiters.
- For Discovery imports, you need to provide the file that was generated by the scanning tool.
The import structure appears on the main configuration page when the import configuration is completed.
To edit or delete the configuration, click the ellipsis (…) then select Edit import structure or Delete.
The import strucutre is now configured, but you still need to map the imported data to the object schema. First, the object types and attributes that will hold the imported data must be created in the schema or identified if they already exist. Then, the data needs to be mapped to the appropriate attributes.
There are two methods for doing this in Assets:
- Automatic data mapping
- Manually mapping data
Automatic data mapping
Automatically create object types and attributes
You'll need to map data to the Assets object schema as part of importing data.
If you import formatted information such as JSON, CSV, or Assets Discovery files, you can enable the Automatically create object types and attributes slider when creating an import structure.
This will create:
- Object types
- Attributes
- Object mapping
When you run an import structure with this option enabled, object types, attributes, and objects should be automatically created for you. If an object type already exists with the same name as the CSV file, Assets will create new objects of that object type.
Mapped object types
The main import configuration page contains mapped object types. Click Edit mapping to reveal them.
Mapped attributes
To view an object type's attribute mappings, click Edit attributes mapping to expand it. For any attributes that didn’t get mapped, you can manually configure a mapping by using the drop-downs at the bottom of the display to select source data and target attributes.
Manually mapping data
Create the necessary object types and attributes
If you manually map your data into Assets, you must create the necessary object types and attributes if they don’t already exist in your schema, to store the incoming data. This includes creating any additional object types to support references in the data.
This task is relatively easy when importing simple CSV files but challenging with other formats or complex data structures. This is why we recommend creating object types and attributes needed for an import automatically because it’s less prone to errors and will properly support all type references in the data.
Map import data
Once you create the necessary object types and attributes in the schema, either manually or automatically, the next step is to map the data to the appropriate object types and attributes. Manual mapping is most straightforward when the data isn’t complex and doesn’t use references.
Configure object type mapping
To begin the configuration, you need to click Create mapping.
The first step is to configure basic parameters for the mapping, most importantly selecting the target object type for the mapping:
👇Click the icons below to explore the fields to configure.
Configure attribute mapping
When the object type mapping is complete, you can map attributes from the data using object type attribute mapping. To start this, click Edit attributes mapping. You must 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 precisely one identifier to run your import.
👇 Click the icons below to see how attribute mapping is laid out.
Map object type references
After mapping attributes, you'll map object type references.
The Object mapping (AQL) field is used when the data is mapped to an attribute referencing another object type. In other words, the mapped attribute is of type Object.
In this situation, an AQL statement is required to match each value being imported against the objects of the referenced type. When a match is found, the ID of the appropriate object is associated with the attribute.
The AQL syntax compares the target attribute in the referenced type and the incoming data values.
Let's explore an example
We have a CSV file with two columns: Name and Operating System.
Name | Operating system |
|---|---|
A1234 | Windows 10 |
B5678 | CentOS Linux |
The import is mapped to the Host object type, with the CSV Name column mapped to the Name attribute, and the CSV Operating System column is mapped to the OS attribute. The OS attribute is of type Object and references the OpSystem object type. This means the value of the OS attribute is set to the Name of an OpSystem object.
To identify the correct OpSystem object, an AQL statement matches the value in each row of the CSV file to the names of the OpSystem objects. When a match is found, the matching OpSystem object is linked to the OS field.
So, in this example, the AQL statement is Name = ${Operating System}, Operating System being the column header in the CSV file.
When importing data that contains cells with multiple values, the AQL syntax is modified slightly. The syntax uses IN instead of equals and contains an index number. If the number is set to 0, all values set for the row will be matched.
TargetAttribute IN (${ImportValue${0}})
Recall that double pipes separate multiple values in a CSV file.
Missing objects target object type
Let's look closer at the Missing objects setting in the object mapping configuration.
The Missing objects setting determines what Assets should do with objects that already exist in the assets schema but aren’t found in the import source. This can happen when performing recurring imports to an object type.
There are three possible settings for the Missing objects configuration.
👇 Click the boxes to see detailed descriptions for each.
Threshold setting for Missing objects
When Missing objects is set to Remove or Update, the Threshold setting determines how many import synchronizations are executed before Assets will take the specified action on missing objects.
👉 For example: If Missing objects is set to Remove, and Threshold is set to 1 synchronization, the object will not be deleted until the second time the data is missing in the import.
You can also set Threshold to a number of days instead of synchronizations.
If the action should be performed immediately during the next import, set Threshold to 0.
Run imports
You can run imports from the import page manually, or you can automate recurring imports directly in your Assets object schemas, so your data stays fresh and trustworthy without the constant manual effort. Ensure that the object type mapping’s status is set to “enabled”.
👇 Click the icons to learn more about running imports from the import configuration.
Assets allows you to run manual and scheduled imports. Once you’ve configured an import source, you can now schedule it to run automatically at regular intervals: once, daily, weekly, or monthly. You can schedule common import types (CSV, JSON), and also app-based imports. To prevent import runs from colliding, if you manually start an import less than 30 minutes before its next scheduled start time, Assets prompts you to continue or cancel.
It is also possible to use Jira Automation to schedule imports, by configuring an automation that uses the Send web request action and calls for Assets import API endpoint. For this, you need the import configuration ID, which is generated after the first manual execution of the import.
Upon completion of the import, only a notification flag will appear, and the user will be invited to click on View history to see the import details.
An entry is added to the Imports history that can be accessed using the View history button in the import tab.
How was this lesson?
next lesson
Build simple Assets automation rules
- Use automation to tackle manual repetitive tasks
- Use Jira Automation with Assets
- Components of an automation rule
- Use variables in your automation rules
- Trigger automation from Assets objects
- Let’s explore an automation use case