Jira Service Management Support

This import type will import objects into Assets with a JSON file. More about importing

You need to be an Assets Manager for an object schema to create, configure, and enable imports.

Skip to:

Before you begin
Importing JSON files
Pre-defined structure and configuration
Import configuration created
Object type and attribute mapping settings
Known limitations

Before you begin

Here are some additional details that you might need to know to import a JSON file:

JSON files that are imported into Assets must follow JSON standards.
The size limit for the JSON file is 10 MB.

Additionally, you can create an object type mapping with or without a selector, but it depends on how the JSON file is structured. If you use the selector, it must be in the format [Attribute.*[Attribute].

Create object type mapping with selector

If you have two or more object types, you must use the selector.

In this example, there are two object types: Location and Server. There’s also an attribute called Location, and its type is Object which makes an outbound reference to the Location Object Type.

{
        "Location": [
            {
                "Name": "Amsterdam"
            },
            {
                "Name": "London"
            },
            {
                "Name": "Madrid"
            }
        ],
        "Servers": [
            {
                "Location": "Amsterdam",
                "Name": "Server1"
            },
            {
                "Location": "London",
                "Name": "Server2"
            },
            {
                "Location": "London",
                "Name": "Server3"
            }
        ]
    }

Create object type mapping without selector

If you have only one object type, you can skip the selector.

In this example, there's an attribute called members, and its type is Object which makes an reference to the object itself.

[
    {
        "members": [],
        "name": "group1"
    },
    {
        "members": [],
        "name": "group2"
    },
    {
        "members": [
            "group2"
        ],
        "name": "group3"
    }
]

Importing JSON files

For testing purposes, you can use the following JSON file sample. By using this file, you can create three Object Types with their mappings and have object references.This file includes the information about cakes, such as batter or topping.

{
	"id": "0001",
	"type": "donut",
	"name": "Cake",
	"ppu": 0.55,
	"batters":
		{
			"batter":
				[
					{ "id": "1001", "type": "Regular" },
					{ "id": "1002", "type": "Chocolate" },
					{ "id": "1003", "type": "Blueberry" },
					{ "id": "1004", "type": "Devil's Food" }
				]
		},
	"topping":
		[
			{ "id": "5001", "type": "None" },
			{ "id": "5002", "type": "Glazed" },
			{ "id": "5005", "type": "Sugar" },
			{ "id": "5007", "type": "Powdered Sugar" },
			{ "id": "5006", "type": "Chocolate with Sprinkles" },
			{ "id": "5003", "type": "Chocolate" },
			{ "id": "5004", "type": "Maple" }
		]
}

If you select the “Name” attribute as Label, you’ll create four objects: “Blueberry”, “Chocolate”, “Devil’s Food”, and “Mail Server”. This will result in a configuration like this:

Configuration example of imported JSON file

To create an Import structure:

From your service project, go to Assets, then Object Schemas.
From the Object Schemas list, select More actions and then select Configure.
In the Schema configuration view, open the Import tab.
Under the Import tab:
- If there’s no import structure, you’ll see the message “You don't have any import connections yet”. Select Create Import configuration to create a new import structure.
- If an import structure has already been created, select Create Configuration.
Select CSV import, then select Next.
Fill in the General, Module, and Scheduling import fields.

General fields

Here are general fields, common for every import type:

Name	Description
Name	The name of the import.
Description	The description for your convenience.
Concatenator	You can specify a default concatenator. When joining multiple data locators into one Assets attribute, this will be the default concatenator. One example could be to join two columns like "First name" and "Last name" into one attribute. So "Mathias" (first name) and "Edblom" (last name) will be concatenated as "Mathias Edblom" if using \s as concatenator. Enter `\s` for space-concatenated. To include a concatenate character, place the value between double quotes (i.e "\s").
Empty Values	Defines what should happen when a Data Locator is empty: Ignore - the existing value in the object will be retained and not overridden by an empty value. Remove - the existing value for the object will be removed, and replaced with an empty field value.
Unknown Values	Defines what should happen if a Data Locator is unknown. This could happen with attribute types like "Status" and "Select". Ignore - the value from CSV will be ignored and the object attribute will be left empty. Add - the value passed in the CSV file will be added to the list and the object attribute will be updated with the new value.
Date Format	Format for date fields in import source to convert dates into Insight. If left empty, Insight will automatically try to find correct format. The format should be specified according to the Java SimpleDateFormat guidelines.
Date/Time Format	Format for date/time fields in import source to convert dates into Insight. If left empty, Assets will automatically try to find correct format. The format should be specified according to the Java SimpleDateFormat guidelines.

Module fields

These fields are specific to an import type (module).

Setting	Description
Import from	Choose a file or URL.
URL	Protocol, Hostname, and Port of where to find the external JSON file. For example: `http(s)://example.com/rest/api/service`
File	Choose a file to upload.
Username	Optional username for basic authentication.
Password	Optional password for basic authentication.
Encoding	The encoding used in the file.

Scheduling fields

Scheduling fields are responsible for keeping your data in sync:

Name	Description
Synchronizing Account	The Jira user to use when synchronize data into Assets. For LDAP and database imports, the account used for synchronization must have Jira admin permissions.
Cron Expression	The interval for the automatic synchronization.
Automatically Synchronize	If the import should be scheduled for automatic synchronization.
Notifications	Select the check box to notify all object schema managers when an import fails.

7. Select Save Import Configuration.

Next, you can create a predefined structure and configuration for your JSON file.

Pre-defined structure and configuration

In the next step, you can create the predefined structure and configuration manually or Assets can create them automatically. To make this process automatic, select:

Create predefined structure – this will create object types with attributes and relationships in the schema
Create predefined configuration – this will create type mappings in the import configuration.

Create predefined structure and configuration window

For the JSON import, the predefined structure and configuration will be created based on the JSON file or URL present in the configuration. Some object type mappings might be disabled by default. Ensure that all object type mappings are enabled.

Import configuration created

You can now view your import configuration, but it's not ready yet. You still need to create or review the object type and attribute mapping, and make sure there are no problems with your import configuration.

When you're ready, go to 2. Create object type and attribute mapping.

Before you go

In the next step, you'll create the object type and attribute mapping. Here are some settings specific to the JSON import type.

Object type mapping settings

Name

Description

Selector

The selector for the JSON import.

Use [Attribute.*[Attribute]]

Exemple:

"items"
"items.item"
"json.data.systems"

Only JSON arrays are valid as selector.

Attribute mapping settings

Name	Description
attribute1[].attribite2[]..	The data locators provided are depending on the JSON and the selector configured.

Known limitations

Currently, the JSON import doesn’t support the use of OAuth tokens or API tokens for authentication when importing the JSON file using a URL. Only basic authentication is supported. As a workaround, you can save the JSON file on Jira's host and import the file again. This method can be used to bypass authentication issues, but it doesn’t support automatic, scheduled imports directly from external sources.

To automate schedule imports directly from external sources, you can save new JSON output with the same filename and archive older versions with a date and timestamp. This allows the use of scheduled file upload imports, but requires careful file management to ensure the correct file is imported each time.

Jira Service Management Support

Products

Jira Software