From Insight 5.0 the new improved import functionality was released. This functionality includes the possibility to write your own custom import module for Insight. The idea is to create a module that structures external data in a two dimensional way and enabling that data to Insight. This page will illustrate how you can achieve your own custom Insight import module.
Read the general concepts of the import functionality here before creating your own import module
First things first, responsibilities. Insight is responsible for creating, validating and mapping the data in Insight, 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 Add-on
First you need to create a new JIRA add-on to use when building your Insight 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
You need to install insight 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:
Add Insight Descriptor
This is an example of an Insight Import descriptor and it must be added to the "atlassian-plugin.xml" in your add-on.
This is the details description how to setup the Insight descriptor:
|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 Insight UI import section.|
|class||Attribute||Yes||The class that implements the Insight interface in order to get the import to work.|
|description||Element||Yes||A description about import type. Will be shown in Insight UI import section.|
|icon||Element||No||A link to the icon to use in the Import Section.|
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)
Specify true/false. If this is true, Insight 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
The structure is a way for the Import module to specify an Insight 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 Insight 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 Insight 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:
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
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:
You can download an example implementation here (The Tempo Account Import): https://bitbucket.org/mathiasedblom/insight-import-module-tempo-account