Create your own import type
From Insight 5.0 the new improved import functionality was released. This functionality includes the possibility to write your own custom import module for Assets. The idea is to create a module that structures external data in a two dimensional way and enabling that data to Assets. This page will illustrate how you can achieve your own custom Assets import module.
Read Understanding import concepts before creating your own import module
Responsibilities
First things first, responsibilities. Assets is responsible for creating, validating and mapping the data in Assets, render the configuration and supply the user with configuration possibilities. The import module is responsible for extracting the external data, structure it in a two dimensional way, declare the needed configuration parts and validate the same configuration.
Create a new Jira app
First you need to create a new JIRA add-on to use when building your Assets Import Type (module). You can read about how to create a new add-on here: https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project
Maven dependencies
You need to install Assets locally into your mvn repository. Download the jar (within the obr) from Atlassian marketplace. Read more about how to do that here: https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html
Add this to the pom.xml:
<dependency>
<groupId>com.riadalabs.jira.plugins</groupId>
<artifactId>insight</artifactId>
<version>${insight.version}</version>
<scope>provided</scope>
</dependency>Add Assets descriptor
This is an example of an Assets Import descriptor and it must be added to the "atlassian-plugin.xml" in your add-on.
<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 the details description how to setup the Assets descriptor:
Name | Type | Required | Description | |
|---|---|---|---|---|
| key | Attribute | Yes | The key of the import type. Must be unique so make sure you are using your own prefix. | |
| name | Attribute | Yes | The name of the import type. Will be shown in Assets UI import section. | |
| class | Attribute | Yes | The class that implements the Assets interface in order to get the import to work. | |
| description | Element | Yes | A description about import type. Will be shown in 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 let the import to executed a validation method when importing objects. This method is a part of the Interface to implement (optional) | |
predefined-implementation | Element | No | Specify true/false. If this is true, Assets will try to create predefined structure and configuration. This is the methods:
|
The interface to implement
The module class described in the descriptor above will have to implement the InsightImportModule interface consult the javadoc for definition of the interface and helper classes.
Predefined structure
The structure is a way for the Import module to specify an Assets Object Type structure that is suitable target for the import. It is not required from an import module perspective and it is not compulsory for the user to use the suggested structure.
The developer of the module creates a structure by specifying a tree structure based on the ExternalFormat. The tree should be based of a number of ObjectTypeExternal which represents an Assets Object Type. The tree is created by appending one or more children to the ObjectTypeExternal along with the attributes that should be present.
If the user wishes to add a predefined structure, a call from Assets will be made to the import module together with the object type root to start from. Below is the method that needs to be implemented:
ExternalFormat predefinedStructure(ImportModuleConfiguration configuration)
Predefined configuration
It's also possible to create a predefined configuration for the import module. Below is the method that needs to be implemented:
|
It contains a list of ObjectTypeMapping
ImportModuleConfiguration
As you have seen in the code examples we need to specify an module specific configuration that extends the ImportModuleConfiguration interface.
This is an example of an ImportModuleConfiguration:
Example implementation
You can download an example implementation here (The Tempo Account Import): https://bitbucket.org/mathiasedblom/insight-import-module-tempo-account