Page History

The BellaDati Connector SDK is an API written in Java. The main goal is to provide ability for customers to implement their own data connector and integrate it with BellaDati. There are 3 prerequisites to make it work:

• You have to have full access to on-premise installation of BellaDati (otherwise contact your admin or cloud provider)
• Well defined Java package structure and class names that do not interfere with other classes used by BellaDati (will be described in sections below).
• You have prepared JAR file package that contains all necessary parts and was correctly built as it is described in following documentation

Setting up the Connector SDK

The Connector SDK consists of two parts:

• API containing the SDK's interface declarations (Javadoc download)
• example implementation for better understanding of SDK including tests

To use the SDK, download the API jar. The SDK source is available on GitHub.

Setting up the IDE

You will need Java IDE to implement your own connector, for example Eclipse. No special configuration is required for setting up IDE for BellaDati Connector SDK.

Setting up the project

Your custom connector has to be located in package with prefix "com.belladati.sdk.connector" (due to simpler class path scanning) followed by your package name. Usage of company web address as a suffix of Java package structure is good idea. Example:

com.belladati.sdk.connector.my.awesome.company

Your Java project needs at least one dependency - latest Connector SDK API containing the SDK's interface declarations. You can manually set up the dependencies or configure your build tool (Maven, Gradle, etc.) to do it for you.

Using Maven

In your pom.xml file, add the following dependency:

  <dependencies>
      ...
      <dependency>
          <groupId>com.belladati</groupId>
          <artifactId>sdk-connector-api</artifactId>
          <version>0.0.6</version>
          <scope>provided</scope>
      </dependency>
      ...
  </dependencies>

Using Gradle

In your build.gradle file, add the following dependency:

dependencies {
	...
	provided 'com.belladati:sdk-connector-api:0.0.6'
    ...
}

Overview of classes in SDK

This section contains high overview of classes and interfaces that are bundled in SDK. Please see online Javadoc or source code on GitHub for more details.

DataProviderApi

Provides import data (including preview data and data definition) based on given configuration. This is the main entry point to your connector. You have to extend this abstract class in your custom connector and implement also public static method getName (see below for more details).

RowApi

One source row represented as array of String values. You have to implement this interface in your custom connector.

RowsApi

Iterable and Closeable definition of source rows. You have to implement this interface in your custom connector.

PropertyValueApi

Class representing value of property used in DataProviderApi configuration. Contains value, default value and flag if this property is required. String, Integer and Boolean value types are supported. You can use this class to manage parameters for your custom connector.

ProgressBarApi

Progress bar displayed on user interface during import. You can use this reference in your custom connector to update progress status of import action.

ConnectorUtils

Utilities for connector SDK. You can use helper methods in this class to simplify your implementation.

Implementation

Your custom connector must implement the following abstract types: RowApi, RowsApi and DataProviderApi. There is also one additional static method "getMetadata" that has to be implemented in DataProviderApi with following definition:

import org.json.JSONObject;
 
...
/**
 * Optional. Returns JSONObject containing metadata for the custom connector.
 * @return Data provider metadata
 */
public static JSONObject getMetadata() {
	JSONObject metadata = new JSONObject();
    metadata.put("name", "Name of your custom connector");
	metadata.put("description", "Some description");
    metadata.put("logo", "com/belladati/sdk/connector/icon.png");
    //or read from file/string
    //String json = "{ \"description\" : \"This is custom data connector\", \"name\" : \"Custom connector\"}";
    //JSONObject metadata = new JSONObject(json);
	return metadata;
}
 
/**
 * Optional. Returns name of this data provider that should be displayed on the user interface.
 * @return Data provider name if not defined in metadata
 */
public static String getName() {
    return "Name of my your custom connector";
}
 
...

Using metadata

In Connector SDK 1.0+ and BellaDati 2.9.7+ advanced connector behavior can be provided inside metadata. Metadata are defined as org.json.JSONObject instance and are returned by static getMetadata() method defined in your custom connector DataProviderApi implementation class.

Metadata allows you to define:

• Connector name and description
• Connector logo
• Wizard mode
  • Steps with name and description
  • Elements of various types: input fields, HTML code, links

Example:

For detailed metadata description, continue to Connector metadata.

Building

Your custom connector has to be packaged as JAR (Java Archive) with all necessary dependencies. Please discuss usage, versions and scopes of all dependencies with BellaDati team. When you're ready, call your preferred tool to build this project:

Using Maven

mvn clean install

Using Gradle

gradle clean install

Directory "target" will contain the project's jar file and other build artifacts.

Testing

Your custom connector project has to contain tests to verify behavior. You are responsible for your code. Tests should contain also negative scenarios.

Deployment

Search for the lib directory located in your <belladati_installation_folder>/belladati/WEB-INF/lib. Installation folder can differ according the installation path of your application server and according type of application server that you use. To deploy your custom connector to BellaDati please copy built JAR (including dependencies) file into the belladati/WEB-INF/lib folder and do not forget to restart your Application server.

Usage

Custom connectors available on classpath are listed at the end of data sources list:

After you select one of connectors you can customize parameters for selected connector.

After you enter valid parameters and click "Continue" button you can continue with import workflow on common Import Settings page.

BellaDati Connector SDKはJavaで書かれたAPIです。主な目標は、顧客が自分のデータコネクタを実装し、BellaDatiとそれを統合するための機能を提供することです。それを動作させるための3の前提条件があります。

• あなたはBellaDatiのオンプレミスのインストールへの完全なアクセス権を持っている必要があります（そうでなければ管理者またはクラウドプロバイダにお問い合わせください）
• BellaDatiによって使用される他のクラスに干渉しないJavaのパッケージ構造とクラス名を定義されます。（以下のセクションで説明する）
• 必要なすべてのパーツを含むJARファイルパッケージを準備しました。これは、次のドキュメントに記載されているとおりに正しくビルドされています。

コネクタSDKの設定

Connector SDKが2つの部分で構成されます

• SDKのインタフェース宣言を含むAPI(Javadoc onlineとJavadoc download)　
• SDKを含むテストをより良く理解するための例を実装

SDKを使用するには、API jarファイルをダウンロードしてください。SDKのソースはGitHubの上で利用可能です。

IDE設定

独自のコネクタを実装するには、Java IDEが必要です（Eclipseなど）。BellaDati Connector SDKのIDEを設定するための特別な設定は必要ありません。

プロジェクトの設定

カスタムコネクタは、パッケージ名が続き「com.belladati.sdk.connector」プレフィックス（単純なクラスパスのスキャンによる）とパッケージにする必要がある。Javaパッケージ構造の接尾辞として会社のWebアドレスを使用するのは良い考えです。例：

com.belladati.sdk.connector.my.awesome.company

Javaプロジェクトに少なくとも1つの依存関係が必要です  　-　 SDKのインタフェース宣言を含む最新のConnector SDK API。依存関係を手動で設定したり、ビルドツール（Maven、Gradleなど）を設定してあなたのために行うことができます。

Maven使用

pom.xmlファイルに次の依存関係を追加します。

  <dependencies>
      ...
      <dependency>
          <groupId>com.belladati</groupId>
          <artifactId>sdk-connector-api</artifactId>
          <version>0.0.6</version>
          <scope>provided</scope>
      </dependency>
      ...
  </dependencies>

Gradle使用

build.gradleファイルに次の依存関係を追加します。

dependencies {
	...
	provided 'com.belladati:sdk-connector-api:0.0.6'
    ...
}

SDK内にクラスの概要

このセクションでは、JDKにバンドルされているクラスおよびインタフェースの高い概要が含まれています。詳細については、JavadocオンラインとGitHubでのソースコードをご参照してください。

DataProviderApi

特定の構成に基づいてインポートデータを提供します（プレビューデータとデータ定義を含む）。これはあなたのコネクタへのメインエントリポイントです。あなたのカスタムコネクタに、この抽象クラスを拡張し、また公共の静的メソッドのgetNameを実装する必要があります。（詳細は以下を参照）

RowApi

一つのソース行は、文字列値の配列として表現しました。あなたのカスタムコネクタで、このインタフェースを実装する必要があります。

RowsApi

行ソースのIterable とCloseable の定義。あなたのカスタムコネクタにこのインタフェースを実装する必要がある。

PropertyValueApi

プロパティの値を表すクラスがDataProviderApi 構成で使用されます。このプロパティが必要な場合は、値、デフォルト値、およびフラグが含まれます。。String, IntegerとBoolean値の型がサポートされています。あなたのカスタムコネクタのパラメータを管理するためにこのクラスを使用できます。

ProgressBarApi

プログレスバーはインポート時に、ユーザインターフェース上に表示されます。インポートアクションの進捗状況を更新するために、カスタムコネクターにこのリファレンスを使用できます。

ConnectorUtils

コネクタSDK用ユーティリティ。あなたの実装を簡素化するために、このクラスのヘルパーメソッドを使用できます。

実装

カスタムコネクタはRowApi、RowsApiとDataProviderApiなど3抽象型の具象サブクラスを含んでいる必要があります。もう1つの静的メソッド "getName"があります。これは、DataProviderApiの具体的なサブクラスで実装する必要があります。

/**
 * Returns name of this data provider that should be displayed on the user interface.
 * @return Data provider name
 */
public static String getName() {
	return "Name of my your custom connector";
}

ビルディング

カスタムコネクタは、すべての必要な依存関係を持つJAR（JavaArchive）としてパッケージ化する必要があります。使用方法、バージョンとすべての依存関係のスコープをBellaDatiチームに議論してください。準備ができたら、このプロジェクトをビルドするために優先ツールを呼び出します。

Maven使用

mvn clean install

Gradle使用

gradle clean install

「ターゲット」ディレクトリは、プロジェクトのjarファイルや他のビルド成果物が含まれています。

検査

カスタムコネクタプロジェクトには、動作を確認するためのテストが含まれている必要があります。 あなたはあなたのコードを担当しています。 テストには否定的なシナリオも含める必要があります。

展開

あなたの<belladati_installation_folder>/ belladati/ WEB-INF/ libにあるlibディレクトリを検索します。インストール先フォルダは、アプリケーションサーバのインストールパスを応じて、使用するアプリケーションサーバーの種類に従って異なる場合があります。 BellaDatiにカスタムコネクタを展開するにはbelladati/ WEB-INF/ libフォルダにファイル構築されたJARファイル（依存関係を含む）をコピーして、アプリケーションサーバーを再起動することを忘れないでください。

使用法

データ・ソースへの接続の「カスタム・コネクター」オプションをクリックすると、あなたのカスタムコネクタを使用できます。あなたのクラスパスで使用可能なすべてのカスタムコネクタとダイアログウィンドウが表示されます。

コネクタのいずれかを選択し、「続行」ボタンをクリックした後、選択したコネクタのパラメータをカスタマイズすることができます。

有効なパラメータを入力し、「続行」ボタンをクリックした後、あなたは一般的なインポート設定ページで、インポートのワークフローを続行できます。

行ソースのIterable とCloseable の定義。あなたのカスタムコネクタにこのインタフェースを実装する必要がある。