Insight is now part of Jira Service Management Data Center. View the latest documentation

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

Responsibilities

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


Maven dependencies

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:

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

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.

	<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 Insight descriptor:

NameTypeRequiredDescription
keyAttributeYesThe key of the import type. Must be unique so make sure you are using your own prefix.
nameAttributeYesThe name of the import type. Will be shown in Insight UI import section.
classAttributeYesThe class that implements the Insight interface in order to get the import to work.
descriptionElementYesA description about import type. Will be shown in Insight UI import section.
iconElementNoA link to the icon to use in the Import Section.

license-type

ElementNo

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

ElementNo

Specify true/false. If this is true, Insight will try to create predefined structure and configuration. This is the methods:

InsightSchemaExternal predefinedStructure(ImportModuleConfiguration configuration);
TemplateImportConfiguration templateImportConfiguration(ImportModuleConfiguration configuration);

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 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:

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:

TemplateImportConfiguration templateImportConfiguration(ImportModuleConfiguration configuration)

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:

 Click here to expand...
package com.company.insight.import.module.example;

import java.util.Arrays;
import java.util.List;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.atlassian.adapter.jackson.ObjectMapper;
import com.riadalabs.jira.plugins.insight.services.imports.common.external.ImportModuleConfiguration;
import com.riadalabs.jira.plugins.insight.services.imports.common.external.insightfield.InsightFieldConfiguration;
import com.riadalabs.jira.plugins.insight.services.imports.common.external.insightfield.text.InsightFieldPasswordConfiguration;
import com.riadalabs.jira.plugins.insight.services.imports.common.external.insightfield.text.InsightFieldTextConfiguration;

public class ExampleConfiguration implements ImportModuleConfiguration {
    private static final long serialVersionUID = -4473533132810886240L;

    private final Logger logger = LoggerFactory.getLogger(ExampleConfiguration.class);

    private InsightFieldConfiguration exampleTextField;
    private InsightFieldConfiguration examplePasswordField;

    public ExampleConfiguration() {

		// text field
        exampleTextField = new InsightFieldTextConfiguration("textField",
                "Name",
                "This is an example field for a name");
        exampleTextField.setMandatory(true);

        // password field;
        examplePasswordField = new InsightFieldPasswordConfiguration("passwordField",
                "Password"),
                "This is an example field for a password");

    }

    public String getExampleTextField() {
        return (String) exampleTextField.getValue();
    }

    public void setExampleTextField(String exampleTextField) {
        this.exampleTextField.setValue(exampleTextField);
    }

    public String getExamplePasswordField() {
        return (String) examplePasswordField.getValue();
    }

    public void setExamplePasswordField(String examplePasswordField) {
        this.examplePasswordField.setValue(examplePasswordField);
    }

    @Override
    public String toJSON() {
        ObjectMapper mapper = new ObjectMapper();
        return mapper.writeValueAsString(this);
    }

    @Override
    public List<InsightFieldConfiguration> getFieldsConfiguration() {
        return Arrays.asList(exampleTextField, examplePasswordField);
    }
}



Example implementation

You can download an example implementation here (The Tempo Account Import): https://bitbucket.org/mathiasedblom/insight-import-module-tempo-account