拡張機能を使用したカスタム監査カテゴリの作成
ThingWorx Java SDK を使用して、カスタム監査イベントとカスタム監査メッセージを作成できます。ThingWorx Composer からカスタムイベントを追加することはできませんが、次の 2 つの方法によってカスタム監査カテゴリとカスタム監査メッセージを追加できます。
• Composer を使用する。詳細については、カスタム監査カテゴリ を参照してください。
• ThingWorx Extension SDK に基づいて Java 拡張機能を作成する (このトピックではこの方法について説明します)。この方法でもローカライズテーブルを使用する必要がありますが、トークンの作成は、プログラムによって、または Composer ユーザーインタフェースを介して対話的に行うことができます。
このトピックでは、カスタム監査イベント、監査イベントのメッセージ、カテゴリを追加する拡張機能を作成するプロセスについて説明します。カスタム監査カテゴリは、監査イベントに必要な属性を持つエンティティを含むカスタム ThingWorx 拡張機能を作成することによって追加できます。
ThingWorx Extension SDK を使用して Java ベースの拡張機能を作成できます。SDK では、サポートされている ThingWorx Platform のクラスおよび API にアクセスできます。これにより、組み込みのサービスとメソッドが公開され、ThingWorx Platform でエンティティの作成と管理を容易に行えるようになります。プラットフォームで使用可能なクラスの詳細については、Javadoc のドキュメンテーションを参照してください。
監査用の拡張機能を作成するには、以下の手順に従います。
開始する前に
ThingWorx Foundation については、PTC ソフトウェアのダウンロードページから以下のソフトウェアをダウンロードしてください。
• Eclipse Plugin for ThingWorx Extensions
• ThingWorx Extension SDK
Eclipse プラグインをインストールするには、次の操作を行います。
1. Eclipse を開いてワークスペースを選択します。
2. > の順にクリックします。
「Install」ウィンドウが開きます。
3. 「Add」をクリックします。
「Add Repository」ダイアログボックスが開きます。
4. thingworxeclipse-plugin-[バージョン].zip ファイルの内容を同じ名前のフォルダに抽出してから、そのフォルダを選択します。
5. 「ThingWorx」で、「ThingWorx Extension Builder」チェックボックスをオンにし、「Next」をクリックします。
6. ライセンス契約に同意し、「Finish」をクリックします。セキュリティメッセージが表示されます。
7. 「OK」をクリックしてインストールを確認します。
8. インストールが完了した後、Eclipse を再起動します。
インストールを確認するには、 > の順にクリックします。「ThingWorx Extension Project」オプションをリストから選択できます。
新規拡張機能プロジェクトの作成
1. Eclipse で、 > > の順にクリックします。「New Project」ウィンドウが開きます。
2. 「ThingWorx」を展開し、リストから「ThingWorx Extension Project」を選択して、「Next」をクリックします。
3. 拡張機能プロジェクトの名前を入力し、先ほどダウンロードした ThingWorxExtension-SDK-[version]-latest.zip ファイルを選択します。
4. 拡張機能のビルドフレームワークとして、「Gradle」または「Ant」を選択します。これにより、選択内容に応じて、プロジェクト用に gradle.build または build-extension.xml ファイルが作成されます。
5. パッケージのバージョンとベンダー名を入力し、「Finish」をクリックします。
プロジェクトが「Package Explorer」枠に表示されます。
ローカライズテーブルエンティティの作成とトークンの定義
監査イベントがあるエンティティを作成する前に、カスタム監査カテゴリとカスタム監査メッセージ用のトークンを定義する必要があります。拡張機能の一部として含めることができるローカライズテーブルエンティティ内にトークンを定義できます。拡張機能をインポートすると、指定したトークンが ThingWorx Platform のローカライズテーブルエンティティに自動的に追加されます。ローカライズテーブルのデフォルトの XML テンプレートをエクスポートおよび修正することによって、ローカライズテーブルエンティティを作成できます。
プラットフォームで英語用の Default ローカライズテーブルをエクスポートするには、次の手順を実行します。
1. Composer で、「インポート/エクスポート」メニューを開き、「エクスポート」を選択します。
2. 「エクスポートオプション」で、ドロップダウンリストから「ファイルへ」を選択します。
3. 「エンティティ」フィールドで、Default ローカライズテーブルを選択します。
4. 「エクスポート」をクリックします。
Default ローカライズテーブル用の XML ファイルをエクスポートした後、このファイルを XML エディタで開きます。ローカライズテーブルの Rows セクションの下に Row エレメントとしてトークンを手動で追加できます。以下に例を示します。
<Rows>
<Row>
<context/>
<name><![CDATA[audit.AuditCategory.ExampleCustomCategory]]></name>
<usage/>
<value><![CDATA[ExampleCustomCategoryEN]]></value>
</Row>
<Row>
<context/>
<name><![CDATA[com.example.audit.ExampleCustomMessage]]></name>
<usage/>
<value><![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]></value>
</Row>
</Rows>
<Row>
<context/>
<name><![CDATA[audit.AuditCategory.ExampleCustomCategory]]></name>
<usage/>
<value><![CDATA[ExampleCustomCategoryEN]]></value>
</Row>
<Row>
<context/>
<name><![CDATA[com.example.audit.ExampleCustomMessage]]></name>
<usage/>
<value><![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]></value>
</Row>
</Rows>
以下の表では、カスタム監査カテゴリの Row エレメントの構文について説明しています。
|
エレメント
|
値
|
説明
|
||
|---|---|---|---|---|
|
name
|
<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>
|
audit.AuditCategory. の部分は、カスタム監査カテゴリ名を定義するプレフィックスです。この例では、このプレフィックスの後にカテゴリ名 ExampleCustomCategory が続きます。
|
||
|
value
|
<value><![CDATA[ExampleCustomCategoryEN]]></value>
|
カスタムカテゴリトークンの値を定義します。英数字、スペース、アンダースコアを含めることができます。この例では、値が Example Custom Category EN という文字列に設定されています。
|
以下の表では、カスタム監査メッセージの Row エレメントの構文について説明しています。
|
エレメント
|
値
|
説明
|
||
|---|---|---|---|---|
|
name
|
<![CDATA[com.example.audit.ExampleCustomMessage]]>
|
監査カテゴリに表示するメッセージを定義します。プレフィックスを定義してから、メッセージの一意の名前を指定する必要があります。
|
||
|
value
|
<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>
|
カスタムカテゴリトークンの値を定義します。単純なメッセージを指定することも、メッセージ内にパラメータを含めることもできます。パラメータは値を参照でき、以下のように 2 つのアンダースコアで囲む必要があります。
__type__
|
拡張機能がサポートする各言語のローカライズテーブルを含める必要があります。たとえば、日本語トークンを含めるには、ja ローカライズテーブルエンティティを作成し、必要なトークンを追加する必要があります。
ローカライズテーブルに対する変更が完了した後、システム上の任意の場所にある LocalizationTables という名前のフォルダに保存します。
拡張機能へのローカライズテーブルエンティティのインポート
必要なトークンを追加した後、前のセクションでエクスポートして修正したローカライズテーブルエンティティをインポートできます。
1. Eclipse で、拡張機能プロジェクトを開き、 > の順にクリックします。「Import」ウィンドウが開きます。
2. 「ThingWorx」で、「Entities」を選択し、「Next」をクリックします。
3. 「Source」フィールドで、「Browse」をクリックし、ローカライズテーブルエンティティが含まれている LocalizationTables フォルダを選択します。
4. インポートするエンティティを選択し、「Finish」をクリックします。
選択したエンティティが拡張機能プロジェクトの /Entities/LocalizationTables/ フォルダの下に追加されます。
新規 Thing エンティティの作成と監査イベントの追加
クラス内のメソッドにアノテーションを追加することで、新規イベントを定義できます。アノテーション付きメソッドは、ランタイムにプラットフォームまたはマッシュアップで実行可能な ThingWorx サービスとしてインポートされます。拡張機能の ThingWorx エンティティにサービスを定義するには、次の手順を実行します。
1. Eclipse で、「ThingWorx」メニューを開き、リストからエンティティタイプを選択します。
2. ソースフォルダとパッケージを入力します。
3. エンティティの名前を入力し、「Next」をクリックします。
4. 「Editable Extension Entity」チェックボックスをオンにし、「Finish」をクリックします。
指定したパッケージの /src フォルダの下に Java ソースファイルが作成され、metadata.xml ファイルが自動的に更新されます。
イベントの監査の有効化
拡張機能で、一連の条件が満たされた場合にトリガーされるイベントを定義できます。イベントを使用して、カスタム機能を持つサービスをトリガーできます。イベントにはデータシェイプが事前に定義されている必要があります。データシェイプにはイベントに関連するデータが保管され、このデータには購読によってアクセスできます。監査サブシステムに情報を記録するように ThingWorx イベントを設定できます。イベントの監査を有効にするには、イベントに以下のアスペクトを割り当てる必要があります。
• auditCategoryKey:customCategoryToken
• auditMessageKey:customMessageToken
これらのアスペクトは新規イベントを追加する Java コード拡張機能を作成することによってのみ追加でき、その後でイベントのアスペクトを手動で定義します。
次のセクションでは、イベントのアスペクトの定義について例を挙げて説明します。
例: カスタム監査イベントの作成
次のコードは、Thing Template 内の ExampleAuditedEvent という名前の監査イベント定義の例を示しています。このイベントには name、description、category などの標準プロパティが定義され、DataShape が実装されています。監査に必要なアスペクトが aspects の値で定義されています。
イベント定義の詳細については、ThingWorx Javadoc API ドキュメンテーションで以下をサーチしてください。
com.thingworx.metadata.annotations.ThingworxEventDefinition
以下のコードは、監査に必要なアスペクトを含むイベント定義を示しています。
@ThingworxEventDefinitions{
events = {
@ThingworxEventDefinition(
name = "ExampleAuditedEvent",
description = "Event with Audit specific Aspects",
category = "Example",
dataShape = "EntityReference",
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
)
}
)
@ThingworxBaseTemplateDefinition(name = Thing.GENERIC_THING_TEMPLATE)
public class ExampleAuditedEventExtensionThingTemplate extends Thing {
// Customer business logic implementation
}
events = {
@ThingworxEventDefinition(
name = "ExampleAuditedEvent",
description = "Event with Audit specific Aspects",
category = "Example",
dataShape = "EntityReference",
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
)
}
)
@ThingworxBaseTemplateDefinition(name = Thing.GENERIC_THING_TEMPLATE)
public class ExampleAuditedEventExtensionThingTemplate extends Thing {
// Customer business logic implementation
}
以下の手順を実行することで、拡張機能内の ThingWorx エンティティに新規イベントを追加できます。
1. Eclipse で、src フォルダの下のエンティティを右クリックし、コンテキストメニューから > の順に選択します。
2. 以下の情報を入力します。
◦ イベント名
◦ カテゴリ名
◦ イベントに実装されているデータシェイプ。この例では、この値は EntityReference に設定されています。
3. 「Finish」をクリックします。
エンティティに新規イベントが作成され、指定したアノテーションが ThingWorx エンティティの Java ソースファイルに追加されます。デフォルトでは、監査に必要なアスペクトは定義されていません。新規イベントの監査を有効にするには、以下の手順に従って、Java ソース内でアスペクトを手動で定義する必要があります。
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
• audit.AuditCategory.ExampleCustomCategory - Default ローカライズテーブルで定義したカスタムカテゴリのトークン名を指定します。
• com.example.audit.ExampleCustomMessage - ローカライズテーブルで定義したカスタムメッセージのトークン名を指定します。
サードパーティ JAR ファイルの追加
/lib フォルダには、拡張機能用に作成されたカスタム Java クラスを含む JAR ファイル、および拡張機能に必要な追加のサードパーティ JAR ファイルが含まれています。
各 JAR ファイルのエントリが metadata.xml ファイルに含まれていることを確認します。
 |
すでに ThingWorx プラットフォームに含まれているサードパーティ JAR ファイルは拡張機能に追加しないでください。
|
Gradle を使用した拡張機能の構築
拡張機能を構築するには、構築タスクを作成します。
1. Eclipse ツールバーで、「Run」ボタンの横にある矢印をクリックし、「Run Configurations」を選択します。
2. 左側のナビゲーション表示枠で、「Gradle Task」を右クリックして「New Configuration」を選択します。
3. タスクコンフィギュレーション名として Build と入力します。
「Gradle Tasks」タブで、以下のタスクを追加します。
clean
build
build
|
|
「Run Configurations」ウィンドウの「Common」タブで「Run」チェックボックスをオンにすることによって、タスクをショートカットとして「Run」ドロップダウンに追加できます。
|
4. プロジェクトのワーキングディレクトリを選択し、「Apply」をクリックします。
5. ツールバーで、「Run」コマンドをクリックしてから、「Build」を選択します。
以前のバージョンの Eclipse では、Gradle STS プラグインを使用することもできます。
1. パッケージエクスプローラで、build.gradle ファイルを右クリックし、 > の順に選択します。コンフィギュレーションウィンドウが開きます。
2. 「Gralde Tasks」タブで、以下のタスクを追加します。
clean
build
build
3. 「Run」をクリックします。Eclipse のコンソール領域に成功メッセージが記録されます。
拡張機能 ZIP ファイルがプロジェクトの > フォルダの下に作成されます。この ZIP ファイルを ThingWorx Platform に拡張機能としてインポートできます。
Ant を使用した拡張機能の構築
拡張機能でビルドフレームワークとして Ant が使用されている場合、次の手順を実行します。
1. パッケージエクスプローラで、build-extension.xml ファイルを右クリックし、 > の順に選択します。
2. 拡張機能プロジェクトを再表示します。
ZIP ファイルが > の下に作成されます。この ZIP ファイルを ThingWorx Platform に拡張機能としてインポートできます。
拡張機能のインポート
1. Composer で、「インポート/エクスポート」メニューを開き、「インポート」を選択します。「インポート」ダイアログボックスが開きます。
2. 「インポートオプション」で、ドロップダウンリストから「拡張機能」を選択します。
3. 「ブラウズ」をクリックし、前のセクションで作成した拡張機能 ZIP ファイルを選択します。
4. 「インポート」をクリックします。
拡張機能がインポートされます。
監査の変更の確認
Composer では、次のような変化が見られます。
• 監査イベントがある新規エンティティが追加された。
• カスタム監査カテゴリとカスタム監査メッセージのローカライズトークンがローカライズテーブルに追加された。
新しいカスタム監査カテゴリとカスタム監査メッセージをテストするには、拡張機能を介して追加したエンティティのカスタムイベントを実行します。適切なパラメータを指定して QueryAuditHistory または QueryAuditHistoryWithQueryCriteria サービスを実行することで、監査履歴を表示します。使用可能なパラメータの詳細については、使用している実装 (直接永続またはデータテーブル) のトピック監査データのサーチ (クエリー、直接永続)またはオンライン監査データとオフライン監査データ (データテーブル)を参照してください。