Package com.riadalabs.jira.plugins.insight.services.imports.common.external

Interface InsightImportModule<T extends ImportModuleConfiguration>

@PublicApi public interface InsightImportModule<T extends ImportModuleConfiguration>
Interface that an import component must implement. It describes the requirements for an Assets Import Component. All methods will be called by the Assets import engine. Some in configuration mode and some during actual import.
Since:
5.0

  • Method Details

    • dataHolder

      ImportDataHolder dataHolder(T configuration, ModuleOTSelector moduleOTSelector) throws ImportComponentException
      Contains the actual data when importing. This will be specific based on each run and will contain the data (of a file if the source is a file and so forth). The standard ImportDataHolder is the TwoDimensionalConfiguration storing data in memory before inserting them to Insight. It is suitable for most imports
      Parameters:
      configuration - the specific configuration for this module
      moduleOTSelector - the specific external selector for one specific object type. Insight will only import that object type and the return type should be based filtered on this parameter
      Throws:
      ImportComponentException - if the component fails to populate the data holder

    • dataHolder

      default ImportDataHolder dataHolder(T configuration, ModuleOTSelector moduleOTSelector, @Nullable List<DataLocator> configuredDataLocators, @Nullable List<ModuleOTSelector> enabledModuleOTSelectors) throws ImportComponentException
      Contains the actual data when importing. This will be specific based on each run and will contain the data (of a file if the source is a file and so forth). The standard ImportDataHolder is the TwoDimensionalConfiguration storing data in memory before inserting them to Insight. It is suitable for most imports
      Parameters:
      configuration - the specific configuration for this module
      moduleOTSelector - the specific external selector for one specific object type. Insight will only import
      configuredDataLocators - the configured datalocators for the object type. Null means all datalocators for the object type mapping
      enabledModuleOTSelectors - the enabled module selectors. Null means all import source module selectors
      Throws:
      ImportComponentException - if the component fails to populate the data holder

    • importModuleConfigurationTemplate

      T importModuleConfigurationTemplate()
      Retrieve the template configuration this will be additional configuration that is required by the user in order for this component to function properly. It could contain hidden properties i.e. for version handling between different configurations. Typically this configuration contains parameters to connect to the external data source such as URL, username etc

    • predefinedStructure

      InsightSchemaExternal predefinedStructure(T configuration) throws ImportComponentException
      Defines the structure to create within Insight. It is possible to let the component define an Assets structure of object types with attributes. This is done by supplying the object type hierarchy using the external format. The root of the ExternalFormat should be the ObjectTypeExternal
      Throws:
      ImportComponentException - if the component fails to create a predefined structure

    • templateImportConfiguration

      TemplateImportConfiguration templateImportConfiguration(T configuration) throws ImportComponentException
      Returns a preset of an import configuration to be used when an import is created from a component. This config will instruct Insight to create an import configuration template that the user can start working from
      Parameters:
      configuration - the specific configuration for this instance
      Throws:
      ImportComponentException

    • fetchDataLocators

      List<DataLocator> fetchDataLocators(T configuration, ModuleOTSelector moduleOTSelector) throws ImportComponentException
      Retrieves the data locators for the source that should be used when importing. It describes unique pointers where data can be found. Multiple locators can be combined in order to populate an Insight Attribute. E.g. in a CSV file the data locators will be the CSV headers
      Returns:
      A list of data selectors.
      Throws:
      ImportComponentException - if the component fails to load valid data locators

    • validateAndTestConfiguration

      ValidationResult validateAndTestConfiguration(T configuration)
      Validates the supplied configuration. The method should return errors in the form key, value as the response. If the returning map is empty the configuration is assumed valid.
      Returns:
      Never null. Empty map if the configuration is valid. If the configuration is valid a i18n error message should be added as the value and the key should point to the corresponding configuration id that was not valid

    • validateDependencies

      ValidationResult validateDependencies()
      Validates any module dependencies. The method should return errors in the form key, value as the response. If the returning map is empty the configuration is assumed valid.
      Returns:
      Never null. Empty map if the configuration is valid. If the configuration is valid a i18n error message should be added as the value and the key should point to the corresponding configuration id that was not valid

    • validateLicenseForModule

      ValidationLicenseResult validateLicenseForModule()
      Validates the license for this module if the license-type is set to LICENSED. The method should return errors in the form key, value as the response. If the returning map is empty the license is assumed valid.
      Returns:
      Never null. Empty map if the configuration is valid. If the configuration is valid a i18n error message should be added as the value and the key should point to the corresponding configuration id that was not valid

    • validateLicenseForInstance

      ValidationLicenseResult validateLicenseForInstance(T configuration)
      Validates the license for each synchronization, for a specific configuration for a module if the license-type is set to LICENSED. The method should return errors in the form key, value as the response. If the returning map is empty the license is assumed valid. Before each import a validation check is performed and the configuration will be given.
      Returns:
      Never null. Empty map if the configuration is valid. If the configuration is valid a i18n error message should be added as the value and the key should point to the corresponding configuration id that was not valid

    • validateOTConfiguration

      ValidationResult validateOTConfiguration(T configuration, ModuleOTSelector moduleOTSelector)
      Validate the module object type selector based on the configuration. The module is responsible to validate that the selector is correct and that when used in the method {@link #dataHolder(ImportModuleConfiguration, * ModuleOTSelector)} it will return a result and not an exception
      Parameters:
      configuration - the module specific configuration
      moduleOTSelector - the specific object type selector
      Returns:
      Never null. Empty map if the configuration is valid. If the configuration is valid a i18n error message should be added as the value and the key should point to the module ot selector

    • getWarnings

      ImportWarnings getWarnings(T configuration, ModuleOTSelector moduleOTSelector)
      Identifies potential problems with a modules selector and informs the user about them. The problems reported here are not supposed to be of critical nature.
      Parameters:
      configuration - the module specific configuration
      moduleOTSelector - the specific object type selector
      Returns:
      A suitable object for displaying a warning.

    • convertConfigurationFromJSON

      T convertConfigurationFromJSON(String jsonString)
      Reverse operation from the toJSON method found in the ImportModuleConfiguration. This method will be called when deserialize the configuration stored for a particular configuration

    • postFunctionOT

      ValidationResult postFunctionOT(T configuration, ModuleOTSelector moduleOTSelector, int affectedObjectTypeId, com.atlassian.jira.user.ApplicationUser actor)
      Each synchronization of an import type for an import source is wrapped up with this post function. Import Module developers may do things after all objects are imported / synchronized.
      Parameters:
      configuration - the module specific configuration
      moduleOTSelector - the specific object type selector
      affectedObjectTypeId - the object type id that is synchronized
      actor - the specific actor for this synchronization
      Returns:
      Never null. Empty map if the configuration is valid. If the configuration is valid a i18n error message should be added as the value and the key should point to the module ot selector

    • postFunction

      ValidationResult postFunction(T configuration, int affectedObjectSchemaId, com.atlassian.jira.user.ApplicationUser actor)
      Each synchronization of an import type for an import source is wrapped up with this post function. Import Module developers may do things after all objects are imported / synchronized.
      Parameters:
      configuration - the module specific configuration
      affectedObjectSchemaId - the object object schema id that is synchronized
      actor - the specific actor for this synchronization
      Returns:
      Never null. Empty map if the configuration is valid. If the configuration is valid a i18n error message should be added as the value and the key should point to the module ot selector