テナント環境セットアップ¶
項目
テナント環境セットアップ とは¶
デプロイされた各モジュールが動作するための動作前提を構築する処理です。
テナント環境セットアップを実行することにより、 intra-mart Accel Platform の運用を行える状態を構築します。
warの初回デプロイ後、またはモジュールの追加やバージョンアップを行った場合は、 intra-mart Accel Platform の起動後にテナント環境セットアップを実行する必要があります。注意
warの初回デプロイ後、またはモジュールの追加やバージョンアップを行った状態でテナント環境セットアップを実行していない場合、 intra-mart Accel Platform が正常に運用できない場合があるので注意してください。モジュールの動作に必要な事前処理(例:テーブル作成など)が存在する場合、モジュール開発者は、テナント環境セットアップ用の資材を準備する必要があります。
テナント環境セットアップ 仕様¶
テナント環境セットアップ で実行可能な処理¶
テナント環境セットアップで実行できる処理は、次の通りです。
- 前処理プログラムの実行
- テナントデータベースに対するDDLの発行
- テナントデータベースに対するDMLの発行
- テナントマスタ情報のインポート
- 拡張インポートの実行
セットアップ設定ファイル 実行準備¶
セットアップ設定ファイル の作成と配置¶
テナント環境セットアップを実行するモジュールは、セットアップ設定ファイルを用意する必要があります。
例:モジュールID=”jp.co.intra_mart.im_tenant”の場合、次のxmlファイルを用意してください。
WEB-INF/conf/products/import/basic/im_tenant/import-im_tenant-config-1.xmlセットアップ設定ファイルの配置先、および命名の規則について説明します。
セットアップ設定ファイルの配置先ディレクトリ規則は次のとおりです。
WEB-INF/conf/products/import/basic/ %ショートモジュールID%
セットアップ設定ファイルの命名規則は次のとおりです。
import-%ショートモジュールID%-config-%スキーマバージョン%.xml
コラム
セットアップ設定ファイルの初回作成の場合、スキーマバージョンは必ず”1”としてください。
以降、バージョンアップなどのタイミングで追加セットアップが必要となったときは、順次スキーマバージョンを1ずつインクリメントしてセットアップ設定ファイルを作成してください。
セットアップ設定ファイルには、次の定義を記述します。
- 発行するDDLを定義したインポートDDLパス
- 発行するDMLを定義したインポートDMLパス
- インポートするテナントマスタ情報のインポートXMLパス
- 実行する拡張インポートのパス
コラム
セットアップ設定ファイルで定義するインポート対象ファイルを総称して、 「インポートファイル」 と表記します。
インポートファイルをさらに分類し、記述されている内容や形式によって次のように表記します。
インポートDDL
DDL文を記述したSQL形式のインポートファイルのことです。拡張子は 「sql」 です。インポートDML
DML文を記述したSQL形式のインポートファイルのことです。拡張子は 「sql」 です。インポートXML
XML形式のインポートファイルのことです。テナントマスタのインポート情報を定義するファイルに該当します。拡張子は 「xml」 です。セットアップ設定ファイルの記述例を示します。下記では、セットアップ設定ファイルで定義可能なすべての情報を盛り込んでいます。<import-data-config xmlns="http://intra_mart.co.jp/system/service/provider/importer/config/import-data-config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://intra_mart.co.jp/system/service/provider/importer/config/import-data-config import-data-config.xsd "> <!-- 前処理プログラム ※不要な場合、削除してください。 --> <preprocessors> <!-- Javaクラスを指定する場合 ※複数定義が可能です。 [0..*] --> <!-- jp.co.intra_mart.system.service.importer.preprocessing.ImportPreprocessor を継承したJavaクラスの完全修飾クラス名を指定します。 --> <preprocessor-class>jp.co.intra_mart.foo.bar.SampleImportPreprocessor</preprocessor-class> <!-- サーバサイドJavaScriptを指定する場合 ※複数定義が可能です。 [0..*] --> <!-- WEB-INF/jssp/srcなど、サーバサイドJavaScriptのルートからの相対パスを、拡張子".js"をつけて指定します。 --> <!-- 指定したサーバサイドJavaScriptにおける execute 関数が実行されます。 --> <!-- execute 関数は処理結果を Boolean 型で返却する必要があります。 --> <preprocessor-class>sample/sample_preprocessor.js</preprocessor-class> </preprocessors> <!-- データベース系 ※不要な場合、削除してください。 --> <database> <!-- インポートDDL ※複数定義が可能です。 [0..*] --> <!-- SystemStorageからの相対パスを指定します。 --> <create-file>products/import/basic/module_id/ddl.sql</create-file> <!-- インポートDML ※複数定義が可能です。 [0..*] --> <!-- SystemStorageからの相対パスを指定します。 --> <!-- 基本情報と国際化情報を分割して定義します。 --> <insert-file>products/import/basic/module_id/dml.sql</insert-file> <insert-file>products/import/basic/module_id/dml_ja.sql</insert-file> <insert-file>products/import/basic/module_id/dml_en.sql</insert-file> <insert-file>products/import/basic/module_id/dml_zh_CN.sql</insert-file> </database> <!-- テナントマスタ系 ※不要な場合、削除してください。 --> <tenant-master> <!-- 各ファイルパスには、SystemStorageからの相対パスを指定します。 --> <!-- ロール ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <role-file>products/import/basic/module_id/role.xml</role-file> <role-file>products/import/basic/module_id/role_ja.xml</role-file> <role-file>products/import/basic/module_id/role_en.xml</role-file> <role-file>products/import/basic/module_id/role_zh_CN.xml</role-file> <!-- アカウント ※複数定義が可能です。 [0..*] --> <!-- 基本情報のみ定義します。(アカウントには国際化情報がないためです。) --> <account-file>products/import/basic/module_id/account.xml</account-file> <!-- カレンダー --> <!-- カレンダー:カレンダー ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <calendar-file>products/import/basic/module_id/calendar.xml</calendar-file> <calendar-file>products/import/basic/module_id/calendar_ja.xml</calendar-file> <calendar-file>products/import/basic/module_id/calendar_en.xml</calendar-file> <calendar-file>products/import/basic/module_id/calendar_zh_CN.xml</calendar-file> <!-- カレンダー:日付情報セット ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <calendar-day-set-file>products/import/basic/module_id/calendar-day-set.xml</calendar-day-set-file> <calendar-day-set-file>products/import/basic/module_id/calendar-day-set_ja.xml</calendar-day-set-file> <calendar-day-set-file>products/import/basic/module_id/calendar-day-set_en.xml</calendar-day-set-file> <calendar-day-set-file>products/import/basic/module_id/calendar-day-set_zh_CN.xml</calendar-day-set-file> <!-- カレンダー:日付情報 ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <calendar-day-file>products/import/basic/module_id/calendar-day.xml</calendar-day-file> <calendar-day-file>products/import/basic/module_id/calendar-day_ja.xml</calendar-day-file> <calendar-day-file>products/import/basic/module_id/calendar-day_en.xml</calendar-day-file> <calendar-day-file>products/import/basic/module_id/calendar-day_zh_CN.xml</calendar-day-file> <!-- カレンダー:カレンダーマージ ※複数定義が可能です。 [0..*] --> <!-- 基本情報のみ定義します。(カレンダー:カレンダーマージには国際化情報がないためです。) --> <calendar-merge-file>products/import/basic/module_id/calendar-merge.xml</calendar-merge-file> <!-- メニュー --> <!-- メニュー:メニューカテゴリ ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <menu-group-category-file>products/import/basic/module_id/menu-group-category.xml</menu-group-category-file> <menu-group-category-file>products/import/basic/module_id/menu-group-category_ja.xml</menu-group-category-file> <menu-group-category-file>products/import/basic/module_id/menu-group-category_en.xml</menu-group-category-file> <menu-group-category-file>products/import/basic/module_id/menu-group-category_zh_CN.xml</menu-group-category-file> <!-- メニュー:メニューグループ ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <menu-group-file>products/import/basic/module_id/menu-group.xml</menu-group-file> <menu-group-file>products/import/basic/module_id/menu-group_ja.xml</menu-group-file> <menu-group-file>products/import/basic/module_id/menu-group_en.xml</menu-group-file> <menu-group-file>products/import/basic/module_id/menu-group_zh_CN.xml</menu-group-file> <!-- 認可 --> <!-- 認可:リソースグループ ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <authz-resource-group-file>products/import/basic/module_id/authz-resource-group.xml</authz-resource-group-file> <authz-resource-group-file>products/import/basic/module_id/authz-resource-group_ja.xml</authz-resource-group-file> <authz-resource-group-file>products/import/basic/module_id/authz-resource-group_en.xml</authz-resource-group-file> <authz-resource-group-file>products/import/basic/module_id/authz-resource-group_zh_CN.xml</authz-resource-group-file> <!-- 認可:リソース ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <authz-resource-file>products/import/basic/module_id/authz-resource.xml</authz-resource-file> <authz-resource-file>products/import/basic/module_id/authz-resource_ja.xml</authz-resource-file> <authz-resource-file>products/import/basic/module_id/authz-resource_en.xml</authz-resource-file> <authz-resource-file>products/import/basic/module_id/authz-resource_zh_CN.xml</authz-resource-file> <!-- 認可:サブジェクトグループ ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <authz-subject-group-file>products/import/basic/module_id/authz-subject-group.xml</authz-subject-group-file> <authz-subject-group-file>products/import/basic/module_id/authz-subject-group_ja.xml</authz-subject-group-file> <authz-subject-group-file>products/import/basic/module_id/authz-subject-group_en.xml</authz-subject-group-file> <authz-subject-group-file>products/import/basic/module_id/authz-subject-group_zh_CN.xml</authz-subject-group-file> <!-- 認可:ポリシー ※複数定義が可能です。 [0..*] --> <!-- 基本情報のみ定義します。(ポリシーには国際化情報がないためです。) --> <authz-policy-file>products/import/basic/module_id/authz-policy.xml</authz-policy-file> <!-- ジョブスケジューラ ※複数定義が可能です。 [0..*] --> <!-- 基本情報と国際化情報を分割して定義します。 --> <job-scheduler-file>products/import/basic/module_id/job-scheduler.xml</job-scheduler-file> <job-scheduler-file>products/import/basic/module_id/job-scheduler_ja.xml</job-scheduler-file> <job-scheduler-file>products/import/basic/module_id/job-scheduler_en.xml</job-scheduler-file> <job-scheduler-file>products/import/basic/module_id/job-scheduler_zh_CN.xml</job-scheduler-file> </tenant-master> <!-- 拡張インポート ※不要な場合、削除してください。 --> <extends-import> <!-- Javaクラスを指定する場合 ※複数定義が可能です。 [0..*] --> <!-- jp.co.intra_mart.foundation.security.ExtendsImport を継承したJavaクラスの完全修飾クラス名を指定します。 --> <extends-import-class>jp.co.intra_mart.foo.bar.SampleExtendsImporter</extends-import-class> <!-- サーバサイドJavaScriptを指定する場合 ※複数定義が可能です。 [0..*] --> <!-- WEB-INF/jssp/srcなど、サーバサイドJavaScriptのルートからの相対パスを、拡張子".js"をつけて指定します。 --> <!-- 指定したサーバサイドJavaScriptにおける doImport 関数が実行されます。 --> <!-- doImport 関数の第一引数にはテナントIDを渡します。 --> <!-- doImport 関数は処理結果を Boolean 型で返却する必要があります。 --> <extends-import-class>sample/sample_import.js</extends-import-class> </extends-import> </import-data-config>コラム
セットアップ設定ファイルで定義された情報は、定義順に(上から順に)処理されます。
「database」タグ内は必ず次の順序で定義する必要があります。
- create-file
- insert-file
「tenant-master」タグ内に定義可能なタグ群は順不同で自由に定義可能です。インポート順序によっては情報の不整合が発生する場合があるため、適宜調整してください。例
メニューリソースはメニューグループのインポートで登録されますが、この作業の実施前にメニューリソースに対する認可ポリシーをインポートしようとすると、メニューリソースが存在せずに例外が発生する可能性があります。セットアップ設定ファイルのフォーマットファイルについては フォーマットファイル(xsd) を参照してください。
前処理プログラム の作成と配置¶
セットアップ設定ファイルに記述した前処理プログラムを作成します。前処理プログラムの実装については 前処理プログラム サンプル を参照してください。作成したら、セットアップ設定ファイルで指定したパスに配置します。
セットアップ設定ファイルで前処理プログラムを記述していない場合は当作業は不要です。
前処理プログラムの配置先パッケージおよびパスについての規則は特に設けません。各モジュールにおける適当なパッケージおよびパスで定義してください。
インポートファイル の作成と配置¶
セットアップ設定ファイルに記述したインポートファイルを作成します。
作成したら、セットアップ設定ファイルで指定したパスに配置します。配置先は システムストレージ です。パブリックストレージではないので注意してください。セットアップ設定ファイルでインポートファイルを記述していない場合は当作業は不要です。
インポートファイルの配置先、および命名の規則について説明します。
インポートファイルの配置先ディレクトリ規則は次のとおりです。
<STORAGE_PATH>/system/storage/products/import/basic/%ショートモジュールID%[ /任意のディレクトリ]
コラム
ショートモジュールIDディレクトリを作成することにより、モジュール間でのインポートファイルの重複を回避します。
ショートモジュールIDディレクトリ配下のディレクトリ作成は必要に応じて実施してください。
インポートファイルの命名規則は次のとおりです。
可能な限り、ファイル名からインポートされる情報の概要が推測できるようなファイル名をつけてください。
あるモジュールのあるスキーマバージョンでどのインポートファイルが処理されるかは、該当のセットアップ設定ファイルを見れば簡単に確認できるため、ファイル名にモジュールIDやスキーマバージョンの付加を義務付けることはしません。インポートDDL、インポートDMLの記法については セットアップ用SQLファイル / インポートDDL / インポートDML 記法 を参照してください。インポートXMLの記法については、各テナントマスタインポータの仕様書を参照してください。コラム
- インポートDML
- インポートXML
上記のインポートファイルは、原則として次の2種類を用意し、セットアップ設定ファイルで定義してください。
基本インポートファイル
ロケールに関連しない情報のみを持ったインポートファイルです。 保持する情報は以下です。
- キー
- ロケールに関連しないデータ
基本インポートファイルのファイル名には、ロケールIDサフィックスはつけません。
例)
im_workflow-dml.sqlim_admin-role.xml多言語インポートファイル
ロケールに関連する情報のみを持ったインポートファイルです。 保持する情報は以下です。
- キー
- ロケールに関連するデータ
多言語インポートファイルのファイル名には、ロケールIDサフィックスをつけます。また、定義するロケール単位でファイルを分割します。例)
ja ロケールの情報を定義したインポートファイル
im_workflow-dml _ja .sqlim_admin-role _ja .xmlen ロケールの情報を定義したインポートファイル
im_workflow-dml _en .sqlim_admin-role _en .xmlzh_CN ロケールの情報を定義したインポートファイル
im_workflow-dml _zh_CN .sqlim_admin-role _zh_CN .xmlインポータ仕様によりロケールに関連する情報と関連しない情報が明確に分けることのできない場合、基本インポートXMLには 「en」 の情報を定義してください。またこの場合は多言語インポートファイルの用意は不要です。このように管理を行うことで、以下のメリットを見込んでいます。
- モジュール資源の翻訳を実施する際に、インポートファイルに関する翻訳対象の特定が容易になります。
- モジュール資源の翻訳を実施する際に、インポートファイルに関する翻訳元言語の特定が容易になります。
コラム
製品化する上では、基本的には3言語(日本語、英語、中国語(簡体字))分のマスタデータ・サンプルデータを提供します。
コラム
テナントマスタ用インポートXMLのフォーマットファイル(xsd)は、基本インポートXMLと多言語インポートXMLを同じスキーマで作成できるように設計されています。
これは以下のメリットを見込んでいます。
- セットアップ時に利用するインポータと、テナント管理機能「ジョブネット設定」より実行可能なテナントマスタ情報インポートを、同一のインポータでまかなうことができます。
- セットアップの場合は、基本インポートXML / 多言語インポートXML のように分割管理ができます。
- テナント管理機能からの実行の場合は、基本+多言語のインポートXMLを作成し、多言語情報を包含したテナントマスタ情報を一括でインポートすることができます。
コラム
インポートDDLおよびインポートDMLは、テナントデータベースの種類に応じた定義をすることができます。各ファイル名の末尾にデータベースサフィックスを付加することで対応します。実際のモジュールを例にとって説明します。
「テナント管理機能(jp.co.intra_mart.im_service)」モジュールは、 スキーマバージョン=1のセットアップ設定ファイルにおいて、次のインポートDDLを定義しています。<!-- 中略 --> <database> <!-- 中略 --> <!-- im_password_history --> <create-file>products/import/basic/im_tenant/im_password_history/im_password_history-ddl.sql</create-file> </database> <!-- 中略 -->また、 <STORAGE_PATH>/system/products/import/basic/im_tenant/im_password_history ディレクトリには、次のファイルを配置しています。
- im_password_history-ddl.sql
- im_password_history-ddl_sqlserver.sql
この場合のテナント環境セットアップは次のように動作します。
テナントデータベースの種類 テナント環境セットアップ時に読み込まれるインポートDDL Oracle Database im_password_history-ddl.sql PostgreSQL im_password_history-ddl.sql Microsoft SQL Server im_password_history-ddl_sqlserver.sql セットアップ設定ファイル側には、データベースサフィックスを付けずに定義することに注意してください。
マルチデータベース対応の詳細については セットアップにおけるマルチデータベース対応 を参照してください。
拡張インポート の作成と配置¶
セットアップ設定ファイルに記述した拡張インポートを作成します。
作成したら、セットアップ設定ファイルで指定したパスに配置します。
セットアップ設定ファイルで拡張インポートを記述していない場合は当作業は不要です。
拡張インポートの配置先パッケージおよびパスについての規則は特に設けません。各モジュールにおける適当なパッケージおよびパスで定義してください。コラム
インポートファイル群はセットアップでのみ利用されるため、モジュールやスキーマバージョンを意識した構成をとります。それに対して拡張インポートについては、セットアップでのみ利用されるとは限りません。拡張インポートを単体で実行するAPI( jp.co.intra_mart.foundation.security.ExtendsImportManager )が用意されており、セットアップのほか、アプリケーションの任意処理で利用されている可能性もあります。そのため、インポートファイルの場合のようなセットアップに特化した命名・配置規則は、拡張インポートでは採用していません。
テナント環境セットアップ 実行方法¶
システム管理者でログインし、テナント環境セットアップを実行します。
テナント環境セットアップ におけるトランザクション制御¶
テナント環境セットアップ 実行時のトランザクション単位は次のとおりです。
前処理
トランザクション制御は行いません。トランザクション制御が必要な処理を前処理プログラムで行う場合は、独自にトランザクション制御実装を行う必要があります。
DDL
トランザクション制御は行いません。
DML(DML/テナントマスタ情報のインポート)
スキーマバージョン単位でトランザクション制御します。
拡張インポート
トランザクション制御は行いません。トランザクション制御が必要な処理を拡張インポートで行う場合は、独自にトランザクション制御実装を行う必要があります。
例外発生時の動作¶
テナント環境セットアップの実行中に例外が発生した場合、テナント環境セットアップは即時停止し、後続のセットアップ処理は実行しません。
コラム
テナント環境セットアップのすべての処理が正常に完了しない限り、テナントの運用が正しく行えません。
テナント環境セットアップ途中で例外が発生した場合は、後続のセットアップを続ける意味がないため、即時停止します。
コラム
DML(DML/テナントマスタ情報のインポート)で例外が発生した場合、例外発生したモジュール・スキーマバージョンのDMLによって登録された情報はすべてロールバックされます。この状態で再度テナント環境セットアップを実行すると、セットアップは例外が発生したモジュール・スキーマバージョンのDMLから再開します。そのため、DMLで例外が発生した場合は、例外の原因を特定し、問題を解決した後にテナント環境セットアップを再実行することで、環境の再構築を行うことなくセットアップを続行することが可能です。DDLはトランザクション制御を行っていないため、DDL発行中に例外が発生した場合はセットアップの続行は基本的にはできません。拡張インポートに関しては、拡張インポートによる処理内容次第となります。