Creating an import type for Assets

Level of experience:	Advanced. You should have completed at least one intermediate tutorial before working through this tutorial.
Time estimate:	It should take you approximately two hours to complete this tutorial.
Applicable:	Jira Service Management 5.12 and later.

Assets is responsible for creating, validating, and mapping data within Assets. It also renders the configuration and provides users with configuration options. The import module is tasked with extracting external data, structuring it in a two-dimensional format, declaring the necessary configuration components, and validating the configuration.

This tutorial shows how to create a custom import module for Assets. The goal is to develop a module that structures external data in a two-dimensional format and integrates it into Assets. before you begin.

Before you begin

To get the most out of this tutorial, you should know the following:

You might want to get familiar with Assets import concepts.
How to create an Atlassian plugin project using the Atlassian Plugin SDK.

Step 1: Install Assets locally

To start, install Assets locally in your Maven repository. You can download the JAR file (within the OBR) from the Atlassian Marketplace. Explore how to install third party JARs

Then, add the following to your pom.xml file:

1
2
<dependency>
  <groupId>com.riadalabs.jira.plugins</groupId>
  <artifactId>insight</artifactId>
  <version>${insight.version}</version>
  <scope>provided</scope>
</dependency>

Step 2: Add Assets descriptor

Add the Assets import descriptor to the atlassian-plugin.xml file of your app.

1
2
<insight-import key="<your-own-import-module-key>"
                name="<your-own-import-module-name>"
                class="com.company.insight.import.module.ImportExample">
    <description>The description of the import type</description>
    <icon>/download/resources/${project.groupId}.${project.artifactId}/images/icon-example.png</icon>
</insight-import>

This is a detailed description of how to set up the Assets descriptor.

Name	Type	Required	Description
key	Attribute	Yes	The key of the import type. It must be unique, so ensure you're using your own prefix.
name	Attribute	Yes	The name of the import type that will be displayed in the Assets UI import section.
class	Attribute	Yes	The class that implements the Assets interface to enable the import functionality.
description	Element	Yes	A description of the import type that will displayed in the Assets UI import section.
icon	Element	No	A link to the icon to use in the Import Section.
license-type	Element	No	Specify `LICENSED` to execute a validation method when importing objects. This method is part of the interface to implement (optional).
predefined-implementation	Element	No	Specify `true` or `false`. If `true`, Assets will attempt to create a predefined structure and configuration. The methods are: `InsightSchemaExternal predefinedStructur (ImportModuleConfiguration configuration)` and `TemplateImportConfiguration templateImportConfiguration(ImportModuleConfiguration configuration)`.

Interface of implementation

The module class described in the descriptor above must implement the InsightImportModule interface. For a detailed definition of the interface and its helper classes, check out the Javadoc.

Step 3: Predefined structure and configuration

To add a predefined structure and configuration to your app, you need to define a module-specific configuration that extends the ImportModuleConfiguration interface.

The structure allows the import module to specify an Assets Object Type structure suitable for the import. It’s not mandatory from an import module perspective, nor is it compulsory for users to adopt the suggested structure.

The module developer creates a structure by specifying a tree structure based on the ExternalFormat. This tree should consist of several ObjectTypeExternal elements, each representing an Assets Object Type. The tree is constructed by appending one or more children to the ObjectTypeExternal, along with the necessary attributes.

If users wish to add a predefined structure, Assets will initiate a call to the import module, providing the object type root to start from. To add a predefined structure to your app, use the following method:

1
2
ExternalFormat predefinedStructure(ImportModuleConfiguration configuration)

You can also create a predefined configuration for the import module by implementing the following method:

1
2
TemplateImportConfiguration templateImportConfiguration(ImportModuleConfiguration configuration)

This method includes a list of ObjectTypeMapping.

Congratulations!

You've built your own import type.

Example implementation

You can download an example implementation of the Tempo Account Import from Bitbucket. Download an example of import type implementation

Next steps

You might want to explore other tutorials for Assets app developments: