intra-mart Accel Platform IM-共通マスタ インポート・エクスポート仕様書 第10版 2019-04-01

4. インポート

4.1. 概要

IM-共通マスタのインポート機能は、単一期間をインポートするスナップショットインポートと、システム開始日からシステム終了日までの間にいくつかの期間をインポートする全期間インポートがあります。

インポートに使用するデータファイルには、XMLとCSVの2つのフォーマットを使用することができます。
XMLでは複数の期間を扱えるのに対し、CSVでは期間情報は持ちません。
期間以外の扱える情報には差異はありません。
複数の期間、あるいはエンティティごとに異なる期間を持つデータを同時にインポートする場合はXMLでデータファイルを作成してください。
インポートは原則として、データの登録/更新のみとなっています。
既存のエンティティ、エンティティの所属情報を削除することはできませんので注意してください。
ただし例外として内包構成のみ、インポート対象期間の既存情報が削除されます。
内包構成は追記ができず、必ずすべての構成情報をインポートする必要があります。
また、内包構成に関して、一部の内包情報を有効/無効化することはできません。
インポートファイルでは、項目ごとに削除フラグで有効/無効が設定できますが、同一セット内で削除フラグに統一した値を指定する必要があります。
同一セット内で削除フラグの値が異なる場合、最後に位置する項目の削除フラグの値でセット内の全ての内包情報が更新されます。
【表:機能比較表】
  スナップショット 全期間
扱えるロケール 制限なし 制限なし
扱える期間
1期間のみ
すべて同じ開始日/終了日
複数の期間を作成可能
それぞれに任意の期間を設定可能
期間の指定方法 設定ファイルに指定 インポートデータファイル内でに指定
データファイル CSV、XML XML
  • データファイルフォーマットでXMLを選択してスナップショットインポートを実行した場合の注意点
  • XMLデータファイルに開始日/終了日を設定しても無視されます。

  • 複数の期間化情報が記述されている場合は、その中のいずれか1つの期間化情報のみがインポートされます。
    この場合、どの期間化情報を選択するかは選択できず、また必ず特定のものが選択されることを保証していません。

4.1.1. 国際化情報をもつエンティティのインポート

インポートファイルには複数ロケールの国際化情報を記述することができ、記述した国際化情報はすべて登録されます。
記述がないロケールのデータはそのまま残り、削除されることはありません。
その場合は非国際化情報のみが更新されます。
  • CSVでインポートする場合の注意点
    データファイルのフォーマットがCSVの場合、1行に1ロケールのデータを記述します。
    複数のロケールをインポートする場合、1つのデータに対して複数行記述することになりますが、非国際化データはすべて同じ内容で記述する必要があります。
    省略、あるいは異なるデータを記述することはできません。
    以下のリストは、パブリックグループのCSVデータの例です。
    先頭から4つの太字部分 (パブリックグループセットコード、パブリックグループコード、ソートキー、削除フラグ) は必ず同一である必要があります。
【リスト:日本語の英語を持つパブリックグループの例】
public-group,public-group,17,false,ja,サンプルパブリック,サンプル,サンプルパブリック,サンプル
public-group,public-group,17,false,en,sample-public,sample,sample public,sample
  • 1行目が日本語、2行目が英語の情報となる。ソートキー、削除フラグは同じでなければならない。
  • 異なるデータを設定した場合、どちらか一方のデータで登録されます。
    この場合、どちらか特定のものが一定して選択されることを保証していません。

4.1.2. 期間化情報を持つエンティティのインポート

全期間インポートでは、データファイルに記述したとおりの期間が作成されます。
データファイル内の期間情報が連続していない場合、または重複している場合はエラーが発生しインポートは中止します。
スナップショットインポートでは原則、1期間のみがインポート対象になります。
ただし、インポートの期間がシステム開始日からシステム終了日までに満たない場合、複数期間を作成する場合があります。
  • 新しいエンティティをインポートした場合。
  • 国際化情報を持つエンティティに対して、ロケールを追加した場合。(次節で解説)

この場合、インポート対象の1期間以外のデータは自動で補完されるものであり、任意のデータを指定することはできません。

4.1.3. 国際化、期間化情報を持つエンティティの更新

期間化情報を持つエンティティが、国際化情報を持っている場合、すべての国際化情報の期間が同じように変更されます。
インポートデータファイルに記述されていない国際化情報の期間も更新されます。
../../_images/example_of_importing_term_b.png

【図:期間Bをインポートした例】

インポート実行後の濃い灰色の部分が更新対象となる期間です。

  • 日本語(ja)の期間Bはインポートデータで更新する。
  • 英語(en)は、対象ではないので国際化情報は更新しない。開始日と終了日、削除フラグを更新する。
  • 中国語(zh_CN)は、インポート対象の期間Bが作成し、不足する期間Aと期間Cも同時に作成する。

4.2. スナップショットインポート

ある時点での日付上に存在する期間化情報を抽出したデータをスナップショットと呼びます。
スナップショットインポートでは、このスナップショットデータを元にしてインポートすることができます。
  • 期間化情報を持つエンティティすべてに対してインポートの開始日から終了日までの1期間を作成する。
  • 期間化情報を持たないエンティティに対しては期間に関係なく登録/更新する。
  • インポート対象になる期間化情報の開始日、終了日は設定ファイルで設定する。
  • インポートにより作成される期間と既存のマスタ情報に存在する期間が重複する部分は、既存の期間が短縮、または削除される。
  • インポートファイル内のデータは、並び順の制限はない。
  • 同一ファイル内であれば、先にインポートする必要があるデータからインポートする。

4.2.1. スナップショットインポートで作成/更新される期間

スナップショットインポートで作成される期間は、設定ファイルで指定した1期間です。
既存の期間が設定した開始日/終了日上にある場合は、その開始日/終了日で期間が分割されます。

4.2.1.1. 新規追加の場合

  • インポート対象期間の「期間B」が作成されます。
  • この期間のみでは、”全期間のデータを持つ”という制約を満たせないので、前後に期間を追加します。
  • システム開始日からインポート開始日までの期間「期間A」が作成されます。
  • インポート終了日からシステム終了日までの期「期間C」が作成されます。
../../_images/new_addition.png

【図:新規作成】

4.2.1.2. 既存のデータが更新される場合

  • 期間が4つに分割されているエンティティに、ある期間をインポートした場合。
  • 「期間A」の終了日をインポートの開始日に変更します。
  • 「期間B」はインポートの期間に含まれるので、「期間B」は削除します。
  • 「期間C」の開始日をインポートの終了日に変更します。
  • 「期間D」はインポート期間の範囲外なので変更しません。
  • インポートされるデータを、「期間X」として作成します。
../../_images/overwriting_terms1.png

【図:期間の上書き1】

  • 期間が1つだけのエンティティにインポートした場合
  • 「期間A」の終了日をインポートの開始日に変更します。
  • インポートされたデータは、「期間B」として作成します。
  • インポートの終了日からシステムの終了日までの期間「期間C」を作成します。
    開始日/終了日以外は「期間A」と同じものです。
../../_images/overwriting_terms2.png

【図:期間の上書き2】

4.3. 全期間インポート

あるエンティティに対して、システム開始日からシステム終了日までのいくつかの期間情報を纏めてインポートすることができます。
すべての期間化情報に任意の期間化情報を設定してインポートすることができます。
  • 期間化情報を持つエンティティそれぞれが異なる期間情報を持つ。
  • システム開始日からシステム終了日までの連続した期間を設定する必要がある。ある日付で複数の期間を持つことはなく、また期間情報が無くなることはできない。
  • 期間化情報を持たないエンティティに対しては、期間は関係なく登録/更新する。
  • インポートデータファイル内に期間を記述する。
  • 既存のデータで、データの開始日と終了日を変更しない場合でも省略することはできない。
  • すべての期間が、インポートファイルの期間で新しく作成される。
  • 既存の期間を残す場合は同じ内容で定義する。ただし、期間コードは新しく割り振られる。
  • 期間の定義が一部のみである場合はエラーになる。
  • インポートファイル内のデータは、並び順の制限はない。

4.3.1. インポートでAPIがリスナに通知する内容

インポートでは、データの更新にIM-共通マスタのAPIを使用します。
インポート実行中に更新内容がリスナに通知する順番を解説します。
メソッド名の「???」部分はManagerそれぞれのエンティティで異なります。
  • 全期間インポートでは、期間コードを新しく割り振るために期間の変更を複数回実行します。
../../_images/import_target.png

【図:インポートターゲット】

先頭に新しい期間コードを持った期間を作成するため、先頭の期間を後方へ移動します。【図:新しい期間を作成】
システム開始日から始まる期間「期間A」の期間を変更します。
01:   update???Term(期間A)      // 期間A: 今日の日付~システム終了日
02:   remove???Term(期間B)
03:   create???Term(期間X)      // 期間X: システム開始日~今日の日付
../../_images/creating_new_term.png

【図:新しい期間を作成】

  • 新しく作成した期間を全期間に変更し、期間Xで全期間を埋めます。【図:全期間に変更】
04:   update???Term(期間X)      // 期間X: システム開始日~システム終了日
05:   remove???Term(期間A)
../../_images/change_to_all_terms.png

【図:全期間に変更】

「期間X」をインポートデータの1つ目の終了日で分割します。【図:期間Xを分割】
「期間X」の期間化情報を更新します。
06:   createTerm(期間Y)      // 期間Y: 期間2の開始日~システム終了日
07:   updateTerm(期間X)      // 期間X: システム開始日~期間1の終了日
08:   update???(期間X)
../../_images/dividing_term_x.png

【図:期間Xを分割】

「期間Y」をインポートデータの2つめの終了日で分割します。【図:期間Yを作成】
「期間Y」の期間化情報を更新します。
09:   createTerm(期間Z)      // 期間Z:期間3の開始日~システム終了日
10:   updateTerm(期間Y)      // 期間Y: 期間2の開始日~期間2の終了日
11:   update???(期間Y)
最後の期間は分割を実行しません。
「期間Z」の期間化情報を更新します。
12:   updateTerm(期間Z)
13:   update???(期間Z)
../../_images/create_term_y.png

【図:期間Yを作成】