sap-sac-scripting

SAP Analytics Cloud スクリプティング

関連スキル

• sap-dependency-security：ストーリー自動化パイプラインで使用する依存関係、SDK／ツール、ソースを固定した SAC MCP のアップグレードを保護する場合に使用します
• sap-browser-automation：アプリ内での手動認証、同意が必要な Edge プロファイルの再利用、新しい Edge／CDP の起動、認証状態の初期化、ブラウザーの復旧に使用します

このスキルを使用する場面

SAC Analytics Designer スクリプト、Optimized Story Experience スクリプト、ウィジェット API、データソースのフィルタリング／選択ロジック、計画／バージョンのスクリプト、エクスポート／ナビゲーションのハンドラー、パフォーマンスが重要なストーリーロジック、または SAC MCP を利用した自動化を作成またはデバッグする場合に、このスキルを使用します。

SAP Analytics Cloud（SAC）Analytics Designer および Optimized Story Experience でのスクリプティングを包括的に扱うスキルです。

認証済みの SAC ブラウザーランタイムを調査する場合は、アプリ内での手動認証、同意が必要な Edge プロファイルの再利用、新しい Edge／CDP の起動、認証状態の初期化、復旧に sap-browser-automation を使用します。SAC スクリプティング固有の境界については、ローカルの references/edge-cdp-control.md を読み込んでください。ローカルランタイムのトリアージ、ウィジェット状態の確認、承認済みのスクリーンショットには CDP を使用します。無関係なタブには触れないでください。

はじめに

ユーザーが特定のタスクを指定せずにこのスキルを呼び出した場合（例：「SAC スクリプティングについて教えて」「SAC スクリプティングスキルを使って」、または追加の質問がない場合）は、次の構成で案内してください。

ようこそ！SAP Analytics Cloud のスクリプティングをお手伝いします。

まず、どの環境を使用していますか？

1. Analytics Designer — アプリケーションベースのスクリプティング、フル API
2. Optimized Story Experience — ストーリーベースのスクリプティング、OSE API（v2025.20）

次に、どのようなサポートが必要ですか？

• 新しいスクリプトの作成（フィルター、計画、ナビゲーション、エクスポートなど）
• 既存のスクリプトのデバッグ
• パフォーマンスの最適化
• 適切な API メソッドの検索
• 計画操作（バージョン管理、データロックなど）

プラグインのコンポーネント

このプラグインは、SAC 開発向けの専門ツールを提供します。

エージェント（Task ツールで使用）：

• sac-script-debugger - スクリプトエラーのデバッグ、問題の追跡
• sac-performance-optimizer - パフォーマンスのボトルネックの分析と解消
• sac-planning-assistant - 計画操作とバージョン管理のガイド
• sac-api-helper - 適切な API の検索とコード例の提供

コマンド（/command で使用）：

• /sac-script-template - スクリプトテンプレートの生成（フィルター、計画、エクスポートなど）
• /sac-debug - 対話型デバッグガイダンス
• /sac-optimize - パフォーマンス分析と推奨事項
• /sac-planning - 計画操作のテンプレート

フック：

• SAC スクリプトの書き込み時に、よくある問題を自動検証します

MCP のセットアップ

このプラグインには、信頼できる secondsky/sap_analytics_cloud_mcp サーバーに接続する .mcp.json が付属しており、11 のサービス領域（コンテンツ、データエクスポート、データインポート、 マルチアクション、カレンダー、コンテンツ転送、ユーザー管理、モニタリング、スケジュールと公開、 翻訳、スマートクエリ）にわたる 90 個の SAC REST API ツールを利用できます。

SAC MCP はソースからインストールするもので、npm からインストールするものではありません。このサーバーは SAC OAuth 認証情報を受け取り、テナント API ツールを公開するため、信頼するフォークやコミットの固定値を変更する前に、sap-dependency-security を使用してください。

MCP ツールを使用する前に、サーバーがすでにインストールされているか確認してください。

• プロジェクト内に .claude/sac-mcp.local.md があるか確認します
• または、環境変数に SAC_MCP_PATH が設定されているか確認します

インストールされていない場合は、ユーザーに一度だけ次のように尋ねてください。「SAC MCP サーバーのセットアップをお手伝いしましょうか？」

はいの場合は、次の手順を案内してください。

1. クローンしてビルドします。

   git clone https://github.com/secondsky/sap_analytics_cloud_mcp
   cd sap_analytics_cloud_mcp
   git checkout 2020235505d98111c2889598ab2217c1619b6943
   npm ci --ignore-scripts
   npm run build
   

2. 環境変数を設定します。

   • SAC_MCP_PATH — クローンしたリポジトリの絶対パス（例：/home/user/sap_analytics_cloud_mcp）
   • SAC_MCP_COMMIT — 2020235505d98111c2889598ab2217c1619b6943
   • SAC_BASE_URL — SAC テナントのルート URL（例：https://mytenant.eu10.hanacloudservices.cloud.sap）
   • SAC_TOKEN_URL — OAuth トークンエンドポイント
   • SAC_CLIENT_ID / SAC_CLIENT_SECRET — SAC OAuth クライアント設定の値

3. インストールに成功したら、次の内容で .claude/sac-mcp.local.md（Git 管理対象外）を作成します。

   # SAC MCP Installation Record
   - Installed: [date]
   - Repository: https://github.com/secondsky/sap_analytics_cloud_mcp
   - Commit: 2020235505d98111c2889598ab2217c1619b6943
   - Path: [absolute path to build/index.js]
   - Build command: npm ci --ignore-scripts && npm run build
   - Env vars configured: SAC_MCP_PATH, SAC_MCP_COMMIT, SAC_BASE_URL, SAC_TOKEN_URL, SAC_CLIENT_ID, SAC_CLIENT_SECRET
   

これにより、今後のセッションで再度尋ねられるのを防げます。

Q2 2026（2026.8）の新機能

最新の SAC リリースにおける主なスクリプト機能の強化点：

• onAfterExecute イベントの強化 — アップロードイベントにメッセージ、統計情報、拒否されたレコード、ターゲットバージョン、ファイル名が含まれるようになりました
• データエクスポート API のジョブ監視 — 差分抽出ジョブおよび計算ジョブ用の新しいジョブモニタータブ
• データインポートサービス API — SAP Datasphere のパブリックディメンションへのマスターデータのインポート、プライベートバージョンへの外部ファクトデータのインポート
• マルチアクション API のステップ — HTTP 204 レスポンスが許可され、ヘッダーフィールドの制限が強化されました
• S/4HANA へのエクスポートの非推奨化 — 代わりにライトバック統合シナリオを使用してください
• 非対称レポート — 行／列ごとに異なる期間、階層、メジャーを設定できます
• 複合バージョン管理 — ストーリーの設計中に複数の複合バージョンを管理できます

詳細については、references/whats-new-qrc2-2026.md を参照してください。

環境の判定

スクリプトの作成または分析を始める前に、ユーザーが使用している SAC 環境を特定してください。

判定の手がかり：

手がかり	環境
.story、「Optimized Story」、OSE、Story.、Application.getActivePage() に言及している	OSE
Analytics Designer、AnalyticApplication、Designer、.application に言及している	Analytics Designer
追加の文脈なしに「SAC script」／「my script」と言っている	不明

環境が不明な場合は、先に進む前に、簡潔な質問を 1 つだけしてください。

「Analytics Designer と Optimized Story Experience のどちらでスクリプトを作成していますか？使用する API リファレンスが変わります。」

ユーザーが回答した後は、再度尋ねないでください。

確認後、適切なリファレンスを使用してください。

• OSE → references/ose-api-*.md（8 ファイル、Q2 2026、v2025.20）
• Analytics Designer → references/api-*.md（既存ファイル）

レポート用ストーリーのワークフロー

読み取り専用の SAC ストーリー、ダッシュボード、管理レポートには、このワークフローを使用します。プランニングとは別の手順です。ライトバック、バージョンの公開、データアクション、配賦、データロック、その他のプランニング操作は sap-sac-planning に振り分けてください。

1. 契約を明確にする：テナント、ストーリー、データソース、想定する対象者、およびユーザーがモデルの変更を禁止しているかどうかを確認します。ユーザーが明示的により広い範囲を許可しない限り、レポートのみの依頼はストーリーレイヤーの作業として扱います。
2. 実際のメタデータを確認する：選択したモデルを確認し、公開されているディメンション、メジャー、階層、時間フィールド、通貨、比較カテゴリのみを使用します。提案するチャートや KPI に役立つからといって、フィールドを作り出してはいけません。
3. ストーリーレイヤーで設計する：ページ、ウィジェット、フィルター、選択、ナビゲーション、サポートされているストーリー計算を定義します。比較は、実績対予算、予測、または利用可能なその他のカテゴリとして明示的にラベル付けします。
4. 安全に実装する：保存する前に、現在の SAC 領域が Modeler ではなく Story Designer であることを確認します。共通フィルターと依存するウィジェット間の操作は、読み取り専用かつ非破壊的な状態に保ちます。
5. 検証または引き継ぎを行う：sap-sac-test-automation を使用して、ページとウィジェットの準備状況を検証します。認証済みテナントの制御が利用できない場合は、sap-browser-automation とローカルの references/edge-cdp-control.md の復旧手順に従います。それでもアクセスできない場合、ストーリーを作成したと主張してはいけません。手動実行または後日接続したセッションで使用できる、完全なストーリー仕様を提示します。

読み取り専用ストーリーの契約

モデルを変更してはならない場合、以下が許可されます。

• SAC がサポートするストーリーレイヤーの計算、ストーリーページ、チャート、テーブル、KPI カード、フィルター、ナビゲーションの作成または編集。
• ストーリーオブジェクトの名前変更と、ストーリーの保存。
• モデルのメタデータの確認と読み取り専用の検証。

明示的な範囲の指定と承認がない場合、以下は禁止されます。

• モデルのディメンション、メジャー、プロパティ、接続、カレンダー、配賦、設定の編集。
• モデルレベルの計算メジャーの作成、またはマスターデータ、ロール、権限の変更。
• プランニングバージョンの公開、データアクションの実行、ロックの変更、プランニングデータのライトバック。

モデルに必要なフィールドまたはメジャーが公開されていない場合、依存するウィジェットを省略し、その省略を記録します。設計に合わせるためにモデルを変更してはいけません。

実装可能な引き継ぎ

テナントとのやり取りがブロックされた場合、以下を含む、実用可能な仕様を提示します。

• ストーリーの目的、対象者、データソース、および確認済みのモデルメタデータ。
• 解決済みのフィールドのみを使用した、ページごとのウィジェット。
• フィルター、比較の意味、選択、ドリルダウン。
• 省略したウィジェットや未解決のフィールドと、それぞれの理由。
• 読み取り専用の安全制約と、今後必要となる検証証拠。

大規模リファレンス検索の振り分け

大規模な OSE API リファレンスを開く前に、rg で検索します。rg -n "class Chart|interface DataSource|enum Feed|setDimensionFilter|getPlanning|PlanningModel" references/ose-api-*.md のようなパターンを使用し、一致するセクションのみを読みます。

• DataSource、DataAction、DataBinding、DataLocking、DataChangeInsights、結果セットのメソッドには、references/ose-api-datasource.md を使用します。
• Chart、Table、GeoMap、RVisualization、ValueDriverTree、フィード、ビジュアライゼーション API には、references/ose-api-chart-viz.md を使用します。
• Planning、PlanningModel、バージョン、カレンダー、データアクション、プランニングワークフローには、references/ose-api-planning-calendar.md を使用します。
• Application、PageBook、Panel、Popup、Widget、ライフサイクルまたはコンテナー API には、references/ose-api-application-core.md を使用します。
• メソッドシグネチャで Feed、Layout、NumberFormat、VariableValue、その他の SAC 固有の型が参照されている場合、列挙型や型の検索には references/ose-api-types-enums.md を使用します。
• ユーザーが Optimized Story Experience と明示的に指定していない限り、Analytics Designer では小規模な references/api-*.md ファイルを先に使用します。

クイックスタート

スクリプトエディターへのアクセス

• Analytics Designer：編集モード → ウィジェットを選択 → ［スクリプト］タブ
• Optimized Story Experience：詳細モード → ウィジェットを選択 → スクリプトを追加

基本的なスクリプト構造

// Event handler example (onSelect on Chart_1)
var selections = Chart_1.getSelections();
if (selections.length > 0) {
    var selectedValue = selections[0]["Location"];
    Table_1.getDataSource().setDimensionFilter("Location", selectedValue);
}

コア API

DataSource API

Widget.getDataSource() からアクセスします。主なメソッド：

• getMembers(dim, {accessMode: MemberAccessMode.BookedValues}) - ディメンションメンバーを効率的に取得します
• getResultSet() - キャッシュされたデータにアクセスします（getData() より推奨）
• setDimensionFilter(dim, value) - フィルターを適用します
• setRefreshPaused(true/false) - 複数の操作をまとめて実行します

Planning API

Table.getPlanning() からアクセスします。主な操作：

• getPublicVersion() / getPrivateVersion() - バージョンにアクセスします
• publish() - プライベートバージョンをパブリックバージョンに送信します
• copyFromPublicVersion() / copyToPublicVersion() - データをコピーします
• setLock(true/false) - データをロックします

ウィジェット API

• チャート：addMeasure()、addDimension()、getSelections()
• テーブル：addDimensionToRows()、setZeroSuppressionEnabled()
• コンテナー：レイアウトには Panel、TabStrip、PageBook を使用します

Application オブジェクト

グローバルユーティリティ：

• Application.showBusyIndicator() / hideBusyIndicator()
• Application.showMessage(type, text)
• Application.getUserInfo() / getInfo()

パフォーマンスのベストプラクティス

1. バックエンドへの呼び出しを最小限にする

   // Use getResultSet() (cached) instead of getMembers() (backend)
   var data = ds.getResultSet();
   

2. フィルター操作をまとめて実行する

   ds.setRefreshPaused(true);
   ds.setDimensionFilter("Dim1", value1);
   ds.setDimensionFilter("Dim2", value2);
   ds.setRefreshPaused(false); // Single refresh
   

3. onInitialization を空のままにする 負荷の高い操作は、遅延読み込みまたは最初の操作まで延期します。

4. メンバーには BookedValues を使用する

   var members = ds.getMembers("Dim", {accessMode: MemberAccessMode.BookedValues});
   

デバッグ

コンソールへのログ出力

console.log("Debug:", myVariable);
console.log("Selections:", JSON.stringify(Chart_1.getSelections()));

ブラウザーの DevTools

1. F12 キーを押す → ［コンソール］タブ
2. 「Info」タイプでフィルターします
3. タイミングを確認するには、URL に ?APP_PERFORMANCE_LOGGING=true を追加します

同梱リソース

リファレンスファイル（66 ファイル）：

• コア API：references/api-datasource.md、references/api-widgets.md、references/api-planning.md
• 高度な機能：references/api-calendar-bookmarks.md、references/api-advanced-widgets.md
• ベストプラクティス：references/best-practices-developer.md、references/best-practices-planning-stories.md
• 言語：references/scripting-language-fundamentals.md
• Q2 2026 関連の API 更新：references/whats-new-qrc2-2026.md、references/whats-new-2025.23.md、references/chart-variance-apis.md
• ブラウザーランタイムのトリアージ：SAC 固有の制約については references/edge-cdp-control.md を参照してください。認証、Edge/CDP のセットアップ、DevToolsActivePort、ターゲットの選択、復旧には共有の sap-browser-automation を使用します
• OSE API（Q2 2026、v2025.20） — メソッド、パラメーター、戻り値の完全なドキュメント：
  • references/ose-api-application-core.md — Application、PageBook、Panel、Popup、Widget（15 クラス）
  • references/ose-api-widgets.md — Button、Dropdown、InputField、Slider、Switch、Text、TextArea（15 クラス）
  • references/ose-api-datasource.md — DataSource、DataAction、DataBinding、DataLocking、DataChangeInsights（39 クラス）
  • references/ose-api-chart-viz.md — Chart、Table、GeoMap、RVisualization、ValueDriverTree（20 クラス）
  • references/ose-api-planning-calendar.md — Planning、PlanningModel、すべての Calendar クラス（54 クラス）
  • references/ose-api-filtering-selection.md — FilterLine、FilterValue、Selection（11 クラス）
  • references/ose-api-utilities.md — BookmarkSet、MemberInfo、DimensionInfo、Timer、NavigationUtils（37 クラス）
  • references/ose-api-types-enums.md — すべての列挙型：Feed、Layout、NumberFormat、VariableValue（70 クラス）

テンプレート（56 パターン）：

• templates/common-patterns.js - 一般的なスクリプトパターン 40 種
• templates/planning-operations.js - Planning 固有のパターン 16 種

公式ドキュメント

• Analytics Designer API: https://help.sap.com/doc/958d4c11261f42e992e8d01a4c0dde25/release/en-US/
• Optimized Story Experience API: https://help.sap.com/doc/1639cb9ccaa54b2592224df577abe822/release/en-US/
• SAC ドキュメント: https://help.sap.com/docs/SAP_ANALYTICS_CLOUD
• Q4 2025 の新機能: https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/00f68c2e08b941f081002fd3691d86a7/c96a267c5da04fff90bb55313ee9f77c.html

---

SAC バージョン: Q2 2026 (2026.8) | API バージョン: 2025.20 (OSE Q2 2026)