本資料はSpotfire 14.4 (リリースノート、What's New in Spotfire® 14.4)にて新規追加された機能 Action Mods 「アクション mods」の開発方法について紹介します。
概要
- Action Modsは拡張子「*.mod」のファイルとしてローカルまたはSpotfireのライブラリに保存し、分析ファイルから使用できます。
- 他のユーザーと共有することも可能です。
- Action ModsはSpotfire 14.4以降のAnalyst、Web Player、Automation Servicesのいずれでも動作します。
- 一つのAction Mods内で、複数のスクリプト(実行できるもの)を作成することも可能です。
- Action Modsの実行や開発に利用できるAPIは、IronPythonスクリプトと類似しています。
- Action ModsはSpotfire 12.0 LTSにて新規追加された「External actions」機能(TIBCO Cloud Integrationと連携)とは特に関係ありません。
- Action ModsとVisualization ModsはまとめてModsと呼ばれ、機能や利用方法、APIなどが異なりますが、開発方法はほぼ同じです。
- Spotfire 14.4からVisualization Modsの開発方法も改善されています。
動作環境
- Spotfire Server 14.4
- Spotfire Analyst 14.4 ※no-server版でもAction Modsの開発や利用は可能です。
- Spotfire Web Player 14.4
- Spotfire Automation Services 14.4
※バージョン14.4はLTS版ではなく、Innovation版です。
利用方法
Action Mods内のアクションは、以下の操作を行う際に実行されるように構成できます。
- テキストエリア内に配置したコントロール(ボタン、リンクなど)や画像がクリックされた際
- 文書のプロパティの値が変更された際
- グラフィカルテーブル内の動的項目(計算値、スパークライン、アイコン、ブレットグラフなど)がクリックされた際
- 「アクション」フライアウト(Spotfire 14.4からの新機能)からクリックされた際
また、Action Mods内のアクションをビジュアライゼーションへドラッグアンドドロップして追加することもできます。これらのボタンやメニューオプションを押下した際に対象アクションが実行されます。
- フローティングボタン
- 右クリックメニューオプション
- タイトルバーボタン
※ビジュアライゼーションのプロパティ画面の「アクション」タブからは利用できません。こちらの「アクション」は「External actions」機能(TIBCO Cloud Integrationと連携)であり、利用にはTIBCO Cloudに接続する必要があります。
利用条件
Action Modsを利用するには、対象ユーザーによって適切なライセンスを付与する必要があります。
Modsを利用するにあたり、ユーザーを以下の3種類に分けてライセンス管理を行うことを推奨します。
-
Mods開発者・管理者:Modsの開発および管理を行うAnalystユーザー
- Modsを開発を行い、Modsをライブラリに保存・公開するユーザー。
-
Mods使用者:通常のAnalystユーザー
- ライブラリに保存されているModsを利用して分析を作成するユーザー。
- Modsを集中管理するため、ローカルModsの使用を禁止することを推奨。
-
Mods閲覧者:通常のConsumerユーザー
- Modsが利用されている分析を閲覧するユーザー。
- Mods関連ライセンスの付与は不要です。
No. |
ライセンス |
説明 | Mods開発者・管理者に付与 | Mods使用者に付与 | Mods閲覧者に付与 |
---|---|---|---|---|---|
1 | mod を開発する | Spotfire でビジュアライゼーション modまたはアクション modを作成および開発できるようになります。 | 〇 | × | × |
2 | mod を信頼 | 他の開発者が開発した mod を信頼することができるようになります。 | 〇 | × / 〇 | × |
3 | アクション mod をライブラリーに保存 | アクション mod (.mod ファイル) をライブラリーに保存できるようになります。 | 〇 | × | × |
4 | ライブラリーからアクション mod を開く | ライブラリーからアクション mod (.mod ファイル) を開くことができるようになります。 | 〇 | 〇 | × |
5 | ローカル アクション mod を開く/保存 | ローカルのアクション mod (.mod ファイル) を開くまたは保存できるようになります。 | 〇 | × | × |
ライセンスの付与はSpotfire管理者がAnalystのツール⇒管理マネージャー画面にて行えます。
開発概要
Action ModsはJavaScript / TypeScript言語でコードを記述し開発します。
利用できるAPIは以下になります。
特にAction Mod APIの部分は、IronPythonスクリプト/C#開発に利用できるSpotfire API(参考資料)のサブセットであり、ネームスペースやクラス、メソッドなどは類似しています。
.NET Framework APIに関して、Action Mod API内で公開されている「System」以外は使用できません。
また、セキュリティの観点から、一部のSpotfire APIはAction Mod APIでは提供されていません。(参考資料)
- ファイル入出力(CSVファイルの読み書き、イメージやPDFファイルへの出力など。MemoryStreamの利用やライブラリの読み書きは可能)
- reflection(System.Reflection)
- HTTP API
- extension API(拡張開発用、 Spotfire.Dxp.Application.Extension)
- threading API
- event handlers(ExternalEventManager、InternalEventManager)
- Scripting API(IronPython/JavaScriptスクリプトを作成・実行、Spotfire.Dxp.Application.Scripting)
- browser API(例:setTimeout、localStorage)
開発環境
- Spotfire Analyst 14.4
- テストやModsファイルの作成のために使用します。
- Action Modsの保存(ローカルまたはライブラリへ)も実施できます。
- Visual Studio Code (ダウンロードリンク)
-
- コードの開発、デバッグなどのために使用します。
- IntelliSense(型のチェック、関数名の提示など)が利用可能です。
-
- Node.js 20.0 LTS 以降 (ダウンロードリンク)
- Action Modsプロジェクトの新規作成、構成管理、開発サーバーの起動などのために使用します。
- コマンドプロンプトから実行できるように「node.exe」の格納先フォルダのパスをユーザー環境変数「PATH」に追加してください。
注意事項: サードパーティのソフトウェアまたはサービスを入手する場合、そのようなサードパーティのソフトウェアまたはサービスに関連するライセンス条項を理解し、かかる条項に従うのはお客様の責任です。
開発手順
Action Modsの開発は以下の手順で行います。
1.作業フォルダの作成
作業フォルダ(中身が空のフォルダを推奨)を新規作成します。
例:
D:\dev\mods\barchart-tools
2.プロジェクトの新規作成
コマンドプロンプトを起動し、作業フォルダへ移動して以下のコマンドを実行してAction Modsプロジェクトを新規作成します。
npx @spotfire/mods-sdk new action
コマンドを初回実行する際にはNPMパッケージ(@spotfire/mods-sdk)のインストールが必要です。「y」を入力して進みます。
NPMパッケージのインストールが完了した後に、Action Modsプロジェクトが新規作成されます。
3.依存パッケージのインストール
続いて以下の2つのコマンドを実行します。
npm install
npm run build
Action Modsプロジェクトに必要なNPMパッケージのインストールやビルドが行われます。
作業フォルダには以下のフォルダやファイル等が生成されます。
- Action Modsソースコード
- mod-manifest.json
- 「src」フォルダ
- icon.svg
- npmプロジェクトファイル
- package.json
- package-lock.json
- Visual Studio Code設定ファイル
- 「.vscode」フォルダ
- TypeScript設定ファイル
- tsconfig.json
- esbuild設定ファイル
- esbuild.config.js
作成されたAction Modsプロジェクトの概要は以下のファイル(参考資料:Mod Schema)から確認できます。必要に応じてバージョンやID、名前などを変更してください。
.\mod-manifest.json
例:
{
"apiVersion": "2.0", ※参照しているAction Mod APIのバージョン
"version": "1.0", ※本Modsのバージョン
"type": "action", ※本Modsの種類(action / visualization)
"name": "Barchart Tools", ※本Modsの名前(自動的に格納先フォルダから設定)
"id": "barchart-tools", ※本ModsのID
"description": "Description of what the mod does.", ※説明文
"capabilities": [], ※利用しているAPIに必要なケイパビリティ
"icon": "icon.svg", ※本Modsのアイコン
"scripts": [ ※Action Modsに含まれているスクリプトの一覧(本例では1つのみ)
{
"id": "script-id", ※スクリプトのID
"name": "My script", ※スクリプトの名前
"file": "build/my-script.js", ※スクリプトのコード
"entryPoint": "myScript", ※エントリポイントとなる関数の名前
"parameters": [ ※スクリプトへの入力パラメータの一覧
{ "name": "message", "type": "String" }, ※スクリプトへの入力パラメータの名前、データ型
{ "name": "para1", "type": "String" } ※同上
]
}
]
}
4.コードの開発
Visual Studio Codeを使って作業フォルダを開いてコードを書きます。
デフォルトでは以下のスクリプトが生成されます。
.\src\scripts\my-script.ts
スクリプトの処理は「myScript」関数内で書きます。
デフォルトで生成されたコードでは、パラメータ(名前:_message)で指定された文字列をコンソールに出力します。
また、パラメータ「document」や「application」が定義されており、それぞれを使て現在の分析、Analystアプリケーションを参照できます。
5.開発サーバーの起動
Visual Studio Codeのメニュー:Terminal⇒Run Task...を実行して、「Start watchers」を選択し、開発サーバーを起動します。開発サーバーはデフォルトではポート「8090」を使って動作します。
起動後にブラウザ画面(http://127.0.0.1:8090/mod-manifest.json)が開かれますが、閉じても構いません。
Visual Studio Codeのメニュー:Terminal⇒Run Build Task...(Ctrl+Shift+B)を実行して開発サーバーを起動することも可能です。
いずれかの方法で起動した後には以下の3つのタスクが起動され、対応のターミナルが表示されます。
- Mods dev server:Spotfire から接続できる開発サーバー(ポート番号8090で動作)を起動。
- TypeScript watcher:型安全を確保するためにソースコードの変更を監視。
- Mods build watcher:ソースコードに変更があった場合に自動的にビルドを実施。
開発サーバーを停止するには、Terminal⇒Terminate Task...を実行し「All Running Tasks」を選択してすべてのタスクを停止してください。
6.開発サーバーへの接続
Analystでデータを取り込んで分析を新規作成し、または既存分析を開いて、ツール⇒開発⇒Modの開発を開きます。
「開発サーバーに接続」を押して、「開発サーバーURL」(デフォルトで「http://127.0.0.1:8090」が指定済み)を入力して「接続」ボタンを押して、前述で起動した開発サーバーへ接続します。
接続が成功した後の画面表示は以下の通りです。
対象Action Modsが利用できるようになっているため、この画面を閉じて構いません。
ツール⇒開発⇒Modの開発を押して該当画面を再開できます。
7.Action Modsのテスト実行
「アクション」フライアウトから、対象Action Mods内に含まれているスクリプトを実行できます。
対象のAction Mods(本例:Barchart Tools)を展開し、配下にあるスクリプト(本例:My script)の右にある三角のアイコンを押して実行します。
「My script」の場合はパラメータに文字列を指定して実行します。
8.デバッグ
「Modの開発」画面を開いて、「デバッグを開始」を押してデバッグを開始します。
デフォルトではポート「9222」で起動します。
Visual Studio Code内でRun⇒Start Debugging(F5)を実行し、前述と同じポート番号「9222」を入力してデバッグを起動します。
Visual Studio Code内でソースコードの行にブレークポイントを追加できます。
Analyst内でスクリプトを実行すると、Visual Studio Codeのほうで追加されたブレークポイントに処理が止まります。
画面上部に表示されているアイコンを使ってコードの実行を制御できます。
- Continue(F5)
- Step Over(F10)
- Step In(F11)
- Step Out(F12)
- Restart(Ctrl+Shift+F5)
デバッグ完了後にAnalystやVisual Studio Codeの両方ともデバッグを停止してください。
- Visual Studio Code:Run⇒Stop Debugging(Shift+F5)を押して停止できます。
- Analyst:「Modの開発」画面にてデバッグを停止できます。
9.Action Modsの配布
開発完了後に、「Modの開発」画面で「切断」を押して開発サーバーから切断してから、「名前を付けて保存」を押して、対象Action Modsをローカルファイル、またはライブラリへ保存します。
保存したAction Modsファイルは他人に共有して利用することは可能です。
切断する前に、もう一度以下のコマンドを実行して、Action Modsのソースコードをビルドすることを推奨します。
ビルドを実行すると、ソースコードが最小化(minimized)、かつ難読化(obfuscated)されます。
npm run build
10.Action Modsの利用
「アクション」フライアウトから「ライブラリー内の項目を検索...」または「ローカルファイルを参照...」を実行して、ローカルまたはライブラリに保存されているmodファイルを「アクション」フライアウトに追加して利用できます。
IronPythonスクリプトと同様に、ボタン押下時または文書のプロパティの値が変わった際にAction Mods内のスクリプトを実行するように構成することも可能です。
また、Action Mods内のアクションをビジュアライゼーションへドラッグアンドドロップして追加できます。これらのボタンやメニューオプションを押下した際に対象アクションが実行されます。
- フローティングボタン
- 右クリックメニューオプション
- タイトルバーボタン
ビジュアライゼーションに追加されたアクションは表示⇒「ビジュアライゼーションプロパティ(プレビュー)」(Spotfire 14.3の新機能、試験段階)を開いて確認または変更できます。
ボタン押下時などにAction Mods内のスクリプトを実行するように構成した場合、またはドラッグアンドドロップによりスクリプトをビジュアライゼーションに追加した場合、該当Modsファイルやその中に含まれているすべてのスクリプトが分析に埋め込まれるようになります。
「アクション」フライアウトから実行するだけではModsファイルは分析には埋め込まれません。
コードの開発
Visual Studio Code内で「my-script.ts」などのスクリプトを編集した場合には、変更内容が自動的にAnalystに反映されますので、リロードや更新などの操作は不要です。
マニフェストの再ロード
「mod-manifest.json」が変更された場合、Analyst内の「Modの開発」画面にて「マニフェストを再ロード」を押して再ロードする必要があります。
「mod-manifest.json」が変更された後に「マニフェストを再ロード」を実施していない場合にはコードへの変更は一切Analystへ反映されません。
「mod-manifest.json」の再ロードが不要な場合には「マニフェストを再ロード」ボタンがグレー表示で押せない状態になります。
スクリプトの追加
以下のコマンド(例)を実行して、Action Modsに新たにスクリプトを追加できます。
npx @spotfire/mods-sdk add-script create-barchart --name "Create Barchart"
引数:
- add-script:スクリプトを追加するコマンド
- create-barchart:追加するスクリプトのID
- --name "Create Barchart":追加するスクリプトの名前
開発サーバーが起動されていない状態でスクリプトを追加した場合、追加後に以下のコマンドを実行してビルドを行ってください。
npm run build
スクリプトの追加やビルドを実施した後に以下のファイル(create-barchart.ts)とコードが生成されます。
パラメータの追加
以下のコマンド(例)を実行して、既存スクリプトにパラメータを追加できます。
npx @spotfire/mods-sdk add-parameter create-barchart para1 string
引数:
- add-parameter:パラメータを追加するコマンド
- create-barchart:追加先のスクリプトのID(本例では上記で追加したスクリプトのIDを使用)
- para1:パラメータの名前
- string:パラメータのデータ型 ※指定できるデータ型は Mod Schema を参照。
開発サーバーが起動されていない状態でパラメータを追加した場合、追加後に以下のコマンドを実行してビルドを行ってください。
npm run build
パラメータの追加やビルドを実施した後にパラメータの情報は自動的に「mod-manifest.json」などに追加されますが、スクリプトの関数には下記のように手動で引数を追加してからコード内で使う必要があります。
コンソール出力
スクリプトのコード内でコンソール出力を行った場合には以下の画面からコンソール出力の内容を確認できます。
console.log(message);
ボタン押下時などに実行されるように構成すると、該当スクリプトが「Modの開発」画面の「試験」タブの「構成と使用」に表示されるようになります。スクリプトの右側にあるアイコンを押してスクリプトを実行した場合、コンソール出力が画面の下側に表示されます。
「アクション」フライアウトからスクリプトを実行した場合、または直接ボタンを押して実行した場合にはコンソール出力が下記画面には表示されません。
また、コンソール出力は進捗状況報告として進捗ダイアログに表示されます(後述参照)。
サードパーティーJavaScriptライブラリの利用
Action ModsのスクリプトではサードパーティーJavaScriptライブラリを利用することも可能です。「lodash」を利用する例を以下に説明します。
以下のコマンドを実行して、「lodash」をインストールします。
npm install --save-dev lodash @types/lodash
スクリプト内で、以下のように「lodash」をインポートして使用します。
import * as _ from 'lodash';
export function lodashTest2({ document, application }: LodashTest2Parameters) {
console.log('lodash version is ' + _.VERSION);
}
RegisterEntryPoint(lodashTest2);
スクリプトをビルドした後に、利用しているサードパーティーJavaScriptライブラリのコードが対象スクリプトのファイル内に埋め込まれます。同一Action Mods内で、複数のスクリプトが同じJavaScriptライブラリを利用している場合、該当JavaScriptライブラリのコードがそれぞれのスクリプトに埋め込まれており、共有されません。
コード例
グラフの新規作成
下記の例では新しいページを追加し、棒グラフを作成しています。
const { VisualTypeIdentifiers } = Spotfire.Dxp.Application.Visuals;
export function createBarchart({ document, application }: CreateBarchartParameters) {
var page = document.Pages.AddNew();
var bar = page.Visuals.AddNew(VisualTypeIdentifiers.BarChart);
bar.AutoConfigure();
}
RegisterEntryPoint(createBarchart);
通知の表示
下記は通知を表示する例です。
const { NotificationService } = Spotfire.Dxp.Framework.ApplicationModel;
export function notify({ document, application }: NotifyParameters) {
var ns = application.GetService(NotificationService);
ns?.AddInformationNotification("title", "description", "message");
}
RegisterEntryPoint(notify);
進捗ダイアログの表示
IronPythonスクリプトで利用できる「ProgressService」はAction Mod APIでは提供されていないため利用できませんが、Action Modsの実行時には進捗ダイアログ(キャンセルの実施も可能)が表示されます。処理がすぐに終わる場合に進捗ダイアログは見れませんが、事前に進捗ダイアログ上で「完了時に閉じる」を無効化すれば必ず表示されます。
例:
export function longRunTest({ document, application }: LongRunTestParameters) {
function sleep(millis: number) {
var date = Date.now();
var curDate = null;
do {
curDate = Date.now();
} while (curDate - date < millis);
}
sleep(1000);
console.log("waited 1");
sleep(1000);
console.log("waited 2");
sleep(1000);
console.log("waited 3");
sleep(1000);
console.log("waited 4");
sleep(5000);
console.log("done");
}
RegisterEntryPoint(longRunTest);
「console.log()」でコンソール出力させたメッセージは進捗ダイアログに表示されます。
文書のプロパティの値の取得・設定
文書のプロパティの値を取得、または設定する例です。
export function testDocumentProperty({ document, application}: TestDocumentPropertyParameters) {
// 文書のプロパティの値を取得
var val = document.Properties.Get("propertyName");
// 文書のプロパティに新しい値を設定
document.Properties.Set("propertyName", "新しい値");
}
RegisterEntryPoint(testDocumentProperty);
トランザクション内での実行
デフォルト設定ではスクリプトの処理の全体がトランザクション内で実行されます。トランザクション内で実行された場合には一回のUndo / Redo操作ですべての処理を元に戻す、またはやり直すことができます。処理中にキャンセルを実施した場合、または異常が発生した場合にはすべての処理が取り消されます。
スクリプトの処理をトランザクション内で実行させたくない場合、または一部トランザクション内で実行できないAPI(例、Save)を利用する場合には、「mod-manifest.json」を編集してスクリプトの定義部分に「"wrapInTransaction": false」(スクリプト全体でトランザクション内での実行を無効化)を指定してください。
mod-manifest.json
"scripts": [
{
"id": "create-barchart2",
"name": "Create Barchart 2",
"entryPoint": "createBarchart2",
"file": "build/create-barchart2.js",
"wrapInTransaction": false
},
また、上記の設定が指定されていても、下記のように「ExecuteTransaction」を使ってスクリプトの一部の処理をトランザクション内で実行するように構成することも可能です。
const { VisualTypeIdentifiers } = Spotfire.Dxp.Application.Visuals;
export function createBarchart2({ document, application }: CreateBarchart2Parameters) {
var page = document.Pages.AddNew();
var bar = page.Visuals.AddNew(VisualTypeIdentifiers.BarChart);
bar.AutoConfigure();
document.Transactions.ExecuteTransaction(new System.Action(() => {
document.ActivePageReference!.Title = "New page title";
document.ActiveVisualReference!.Title = "New visual title";
}));
}
RegisterEntryPoint(createBarchart2);
開発サーバーのポート番号の変更
開発サーバーはデフォルトではポート番号「8090」上で動作しますが、該当ポートがすでに使用されている場合は50000番以上から任意で空いているポートを使用します。
以下のファイルに「--port 8091」の部分を追記して開発サーバーのポート番号(本例:8091)を明示的に指定することができます。
package.json
"scripts": {
"build": "mods-sdk build",
"build:dev": "mods-sdk build --watch --debug",
"tsc:dev": "tsc --watch",
"server": "mods-dev-server --port 8091 --allow-project-root true"
},
列挙処理
IronPythonスクリプトでは列挙可能なオブジェクト(配列、NodeList、arguments等)から値を取得する際には下記の通りに「for ... in ...」を使用します。
def getVisual(page, visualTitle):
for vis in page.Visuals:
if vis.Title == visualTitle:
return vis
return None
一方で、上記と同等な処理を行う際にTypeScriptでは「for ... of ...」を使用します。
誤って「for ... in ...」を使ってしまった場合はコンパイルエラーにはなりませんが、期待通りの動作にならない可能性がありますので要注意です。(参考資料)
function getVisual(page: Spotfire.Dxp.Application.Page, visualTitle: string) {
for (const vis of page.Visuals) {
if (vis.Title === visualTitle) {
return vis;
}
}
return null;
}
参考資料
- Working with mods - Getting started
- Developing action mods
- Action mods - Tutorial
- Action mods - Snippets (サンプルコード)
- Action mods - FAQ
- Action Mod API