Visual Builder 開発の基礎（変数・アクションチェーン・イベント・サービス接続）

この章の結論

• Visual Builder のアプリは 変数（状態）・コンポーネント（画面）・アクション・チェーン（処理）の3つでできており、それを イベント がつなぎます。
• アクション・チェーンは必ずイベント・リスナーから起動されます。中身は JavaScript のクラス（ActionChain を継承し run(context) を実装）で、Actions.callRest などの組み込みアクションを呼びます。
• 変数・定数・型にはスコープ（アプリケーション、フロー、ページ、フラグメント、レイアウト、アクション・チェーン）があり、そのスコープに入ると作られ、出ると破棄されます。
• データの取得・更新は サービス接続（OpenAPI 形式の REST 定義）経由です。Fusion の REST API はカタログ（Oracle Cloud Applications）から選びます。表への表示には Service Data Provider（SDP） を使います。
• サービス接続はデータへの入口を作るだけで、データ・セキュリティは課しません。権限は Fusion 側のロールで制御します。

全体像

アプリの構造

要素	内容
アプリケーション（App UI・Web アプリ）	最上位の入れ物。App UI は既定で main-start ページを持つ
フロー	関連するページのまとまり。フロー内・フロー間で画面遷移する
ページ	画面。コンポーネント（Oracle JET）を配置する
フラグメント	再利用できる画面部品。ページのタブの中身やページ・テンプレートにも使える
変数・定数・型	画面の状態とデータの構造
アクション・チェーン	イベントで動く処理の並び
サービス接続	REST API の定義（エンドポイントとスキーマ）

Designer で行った変更は、最終的に JSON（メタデータ）と JavaScript のファイルとしてリポジトリに保存されます。

変数と型

種類	例	用途
プリミティブ型	String、Number、Boolean、Any	単純な値
構造型	Object、Array	データ構造
組み込み変数	現在のページ、ユーザー情報など	メタデータの参照
カスタム型	REST の応答に合わせた型	応答の構造を表す

スコープ	使える範囲
application	アプリ全体（ログイン名など）
flow	そのフローと配下のページ
page	そのページだけ
fragment	そのフラグメントだけ（ページの変数は参照できない）
layout	そのレイアウト・コンテナだけ
action chain	そのアクション・チェーンだけ

• 定数は初期化後に値を変えられません。ただし既定値が他の変数を参照する式なら、その変数の変化に合わせて値が変わります。
• 既定値には式を使えます。例：{{ $variables.firstName + ' ' + $variables.lastName }}。参照先が変わると自動で再計算されます。
• ページ変数を入力パラメータにすると、そのページへ遷移するときの受け渡し項目になります。URL のパラメータにもでき、特定データを表示する画面をブックマークできます。
• 変数の値が変わると onValueChanged イベントが発生します。$event.oldValue・$event.value・$event.diff で変化を受け取れます。同じ値を代入しても発生しません。

主な暗黙オブジェクトは $application、$flow、$page、$variables（現在のスコープの変数）、$fragment、$layout、$chain、$parameters、$listeners、$event、$modules です。ユーザー情報は $application.user（username、fullName、email、roles、isAuthenticated など）で取れます。VBS では $application.user.userId は IDCS のユーザー ID（USER_OCID）を返さないため、IDCS のユーザーを基準にする処理は username を使います。

アクション・チェーン

• ユーザー操作などのイベントに応じて、アクションを順番に実行する仕組みです。例：REST を呼ぶ → 結果を変数に入れる、関数を呼ぶ → if で分岐する。
• 必ずイベント・リスナーに結び付けます。部品のイベントを選ぶと自動で作られる場合もあります。
• 1つのチェーン内のアクションは直列に実行されます。イベント・リスナーに複数のチェーンを設定すると並行して動かせます。
• チェーンはそれぞれ $chain というコンテキストを持ち、後続のアクションだけがそこに書いた状態を参照できます。
• 定義する場所でスコープが決まります。App UI レベルはどのフロー・ページからも呼べ、ページ・レベルはそのページだけ、フラグメント・レイアウト・レベルはその中の変数だけを使えます。
• 組み込みアクションには Call REST、Assign Variable、Call Function、Call Action Chain、If、For Each、Switch、Try-Catch、Navigate To Page、Fire Event、Fire Notification、Code（独自コードのブロック）などがあります。足りないものはカスタム・アクションとして作り、Actions.runAction で呼びます。
• フッターの Tests でアクション・チェーンのテストを管理できます。

イベント

種類	例	定義する場所
コンポーネント・イベント	ボタンの ojAction	Page Designer のプロパティ・ペイン
変数イベント	onValueChanged（唯一の変数イベント）	変数エディタ
カスタム・イベント	Fire Event アクションや fireCustomEvent() で発生	アクション・チェーン・エディタ、イベント・エディタ
ライフサイクル・イベント	vbBeforeEnter、vbEnter、vbBeforeExit、vbExit、vbAfterNavigate	イベント・リスナー・エディタ

ライフサイクル・イベント	発生するタイミング
vbBeforeEnter	ページへ遷移する前（ページ変数はまだないため $parameters で入力パラメータを読む）
vbEnter	フロー・ページの変数がすべて初期化されたとき（初期データの取得に使う）
vbBeforeExit	ページを離れる前（cancelled: true を返すと遷移を取り消せる。未保存の変更の確認に使う）
vbExit	フロー・ページを離れる前
vbAfterNavigate	ページへの遷移が完了したとき

ほかに、Fire Notification アクションで発生する vbNotification、データ・プロバイダの暗黙の取得で重大なエラーが起きたときの vbDataProviderNotification、アプリが更新されたことを知らせる vbResourceChanged があります。

サービス接続（Fusion REST を含む）

• バックエンドは REST API をホストする外部システムの表現で、サービス接続はそのエンドポイントとスキーマを OpenAPI 形式で持つ定義です。
• App UI では、Unified Application が Oracle Cloud Applications という組み込みのバックエンドを提供します。依存関係（Unified Application を含む）から来たサービス接続・バックエンドは変更できませんが、自分で作ったものは拡張内のすべての App UI で使えます。
• 自分のサービス接続を他の拡張から使わせるには、Accessible to application extensions を付けます。
• サービス接続は拡張レベルで定義されます。データ・セキュリティは課さないため、REST 側の権限が実質的な防御線です。

作り方は3通りです。

作り方	使う場面
Select from Catalog	Fusion の REST API（Oracle Cloud Applications カタログ）など、カタログにあるサービス
Define by Specification	ADF の describe や OpenAPI の定義から作る。カタログに目的のリソースがないとき
Define by Endpoint	URL を直接指定する

カタログから作るときは、Metadata Retrieval Option を選びます。

選択肢	動き
Dynamically retrieve metadata	常にサービスのメタデータからエンドポイント定義を取得する
Copy full OpenAPI to the application	定義をアプリのソースに保存する（静的なサービス接続）
Copy minimal OpenAPI to the application（既定）	選んだエンドポイントの最小限の定義を保存し、スキーマは必要なときに取得する。ADF の describe ベースのサービスに推奨

Automatically include list of values (LOV) を選ぶと、対象オブジェクトの LOV がすべて含まれる代わりに openapi3.json が大きくなり、性能に影響することがあります。

Service Data Provider（SDP）

SDP は、サービスのエンドポイントからデータを取得して、表・リスト・選択リスト・グラフなどにバインドできるデータ・プロバイダです。Oracle Cloud Applications のサービスでは、組み込みの変換（Business object REST API の transforms）により、並べ替え・絞り込み・ページングが自動で効きます。主なプロパティは次の通りです。

プロパティ	内容
endpoint	サービス名/エンドポイント名 の形式
keyAttributes	行のキーになる項目
itemsPath	応答の中でコレクションが入っている場所
filterCriterion	絞り込み条件。{ op, attribute, value } か、{ op, criteria } の組み合わせ
sortCriteria	並べ替え。{ attribute, direction } の配列
pagingCriteria	既定の件数・開始位置など
responseType	応答の型。取得する項目の決定にも使われるため、常に設定するのが推奨

filterCriterion は、Business object REST API では q パラメータに変換されます。たとえば { "op": "$eq", "attribute": "empName", "value": "Lucy" } は q=empName = 'Lucy' になります。

ビジネス・オブジェクト

Visual Builder のビジネス・オブジェクトは、Web アプリ用に Visual Builder 側で定義・保存する独自のデータ（表に相当）です。REST API が自動で用意され、検証やトリガーなどのルールも定義できます。既定の保存先のほか、自分のデータベース・スキーマに切り替えることもできます。

App UI の拡張では、独自のビジネス・オブジェクトは作れません。Fusion のデータはサービス接続で使い、独自の DB が必要な要件は Visual Builder の Web アプリで作ります（拡張の全体像）。なお Fusion の文脈では、REST のリソース（例：請求書）を「ビジネス・オブジェクト」と呼ぶこともあるので、どちらの意味かを区別して読みます。

JavaScript

• ページ・フロー・アプリケーションのそれぞれに JavaScript モジュールがあり、関数を追加できます。アクション・チェーンからは $functions.関数名（現在のスコープ）で呼べます。
• 外部ライブラリは RequireJS で参照できます。グローバル関数としてモジュールを取り込むと、式から $modules.モジュール名.関数名() で呼べます。
• 使いどころは、値の整形・変換など画面内で完結する処理です。業務ロジックの正しさはサーバー（Fusion）側で担保します。

設定・実装の手順

Fusion の未払い請求書を一覧表示する App UI のページを作る流れです（Advanced モード）。

1. App UI を作る：ワークスペースのナビゲータで App UIs の + > Create App UI を選び、名前を入れます。App UI ID の x- 接頭辞は残します（顧客が作った App UI を Oracle のものと区別するため）。
2. サービス接続を作る：Services > + > Service Connection > Select from Catalog で Oracle Cloud Applications のカタログを開き、サービス名を付け、使うエンドポイントだけを選びます。Metadata Retrieval Option は既定（Copy minimal OpenAPI）で始めます。
3. 型を作る：応答に合わせたカスタム型を、エンドポイントから作ります（Create a Type From an Endpoint）。
4. 表を置く：main-start ページに表を配置し、プロパティ・ペインの Quick Start でデータを対応付けます。SDP 型の変数とバインドが作られます。
5. ボタンと処理を作る：ボタンの ojAction イベントからアクション・チェーンを作り、Call REST と Fire Notification を組み合わせます。
6. 確認する：Preview で動かし、フッターの Audits でエラー・警告がないことを確認します。
7. 公開する：コミット・プッシュ、マージ・リクエスト、Publish の順に進めます（Visual Builder Studio の基本）。

コード例

REST の応答と条件を先に確かめる

画面に結び付ける前に、使う項目と q の書き方を curl で確認しておくと、手戻りが減ります。練習用モック API（本物の Oracle API ではありません）で試せます。

モック API で未払い請求書を確認する

export BASE="https://<このサイトのURL>/api/mock/fscmRestApi/resources/11.13.18.05"
curl -s -u learner:welcome1 -H "REST-Framework-Version: 2" \
  --get "$BASE/invoices" \
  --data-urlencode "q=PaidStatus = 'Unpaid'" \
  --data-urlencode "fields=InvoiceId,InvoiceNumber,Supplier,InvoiceAmount,BusinessUnit" \
  --data-urlencode "limit=5" \
  --data-urlencode "onlyData=true"

実環境では、接続先と認証情報をプレースホルダ・環境変数にします。

実環境（例）

curl -s -u "$FUSION_USER:$FUSION_PASSWORD" \
  "https://<your-pod>.fa.<region>.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices?limit=5&onlyData=true"

SDP 型の変数（ページの JSON）

endpoint の apInvoices はサービス接続を作るときに付けた名前の例です。実際のエンドポイント ID は、サービス接続の画面で確認してください。

main-start-page.json の variables（抜粋・例）

"invoicesSDP": {
  "type": "vb/ServiceDataProvider",
  "defaultValue": {
    "endpoint": "apInvoices/getall_invoices",
    "keyAttributes": "InvoiceId",
    "itemsPath": "items",
    "responseType": "invoiceListType",
    "filterCriterion": {
      "op": "$and",
      "criteria": [
        { "op": "$eq", "attribute": "PaidStatus", "value": "Unpaid" },
        { "op": "$eq", "attribute": "BusinessUnit", "value": "{{ $variables.selectedBU }}" }
      ]
    },
    "sortCriteria": [
      { "attribute": "InvoiceDate", "direction": "descending" }
    ]
  }
}

selectedBU 変数を変えると SDP の onValueChanged が働き、表が自動で再取得されます。

JavaScript のアクション・チェーン

アクション・チェーンを作ると、VBS は次のようなクラスの雛形を生成します。組み込みアクションは Actions.<アクション名>(context, { ... }) の形で呼びます。

loadUnpaidInvoicesChain.js（例）

define([
  'vb/action/actionChain',
  'vb/action/actions',
  'vb/action/actionUtils',
], (
  ActionChain,
  Actions,
  ActionUtils
) => {
  'use strict';

  class loadUnpaidInvoicesChain extends ActionChain {

    /**
     * @param {Object} context
     */
    async run(context) {
      const { $application, $constants, $variables } = context;

      const response = await Actions.callRest(context, {
        endpoint: 'apInvoices/getall_invoices',
        uriParams: {
          q: "PaidStatus = 'Unpaid'",
          onlyData: true,
        },
      });

      if (!response.ok) {
        await Actions.fireNotificationEvent(context, {
          summary: '請求書を取得できませんでした',
          message: `HTTP ${response.status} ${response.statusText}`,
          type: 'error',
        });
        return;
      }

      // 複数件の応答は body の中に入る（Fusion の REST では items 配列）
      $variables.unpaidInvoices = response.body.items;
    }
  }

  return loadUnpaidInvoicesChain;
});

Call REST の戻り値は、成功時に ok: true・status・body・headers、失敗時に ok: false・status・statusText・message を持ちます。実務では次の点を足します。

• エラー処理：response.ok を必ず確認し、Try-Catch で想定外の例外も受けます。
• ページング：Call REST で直接呼ぶ場合は、応答の hasMore と offset を見て続きを取得します。表示だけなら SDP に任せる方が簡単です。
• リトライ：一時的なエラー（タイムアウトなど）だけを対象に、回数の上限を決めて再試行します。更新系（POST・PATCH）は二重登録に注意します。

ページの JavaScript 関数

main-start-page.js（例）

define([], () => {
  'use strict';

  class PageModule {
    /**
     * 金額を円表記に整形する
     * @param {number} amount
     * @return {string}
     */
    formatJpy(amount) {
      return new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' })
        .format(amount ?? 0);
    }
  }

  return PageModule;
});

main-start-page.html（抜粋・例）

<oj-bind-text value="[[ $functions.formatJpy($variables.totalAmount) ]]"></oj-bind-text>

落とし穴とベストプラクティス

よくあるミス

• コンテキストの変数を別名に入れる：const pageVars = $page.variables のような再代入はしない。監査（Audits）やテストは文字列検索で変数の使用箇所を探すため、$page.variables.var1 のように完全な形で参照します。
• vbBeforeEnter でページ変数を使う：まだ存在しません。$parameters を使います。
• 同じ値の代入で onValueChanged を期待する：値が実際に変わらないと発生しません。
• サービス接続でセキュリティを担保したつもりになる：サービス接続はデータ・セキュリティを課しません。
• LOV をすべて含めてカタログから作る：openapi3.json が肥大化して遅くなります。必要なエンドポイントだけを選びます。

• 取得する項目は responseType（または fields）で絞り、応答を小さくします。
• 画面の計算結果（合計など）は表示用と割り切り、正式な値は Fusion 側の処理で確定させます。
• 共通の処理はフラグメントや JavaScript モジュールにまとめ、ページごとにコピーしないようにします。

試験対策ポイント

• 対応する試験：Redwood 模擬テスト の「VBS による Fusion アプリ開発（Configure service connections in Visual Builder Studio）」「VBS による Fusion Cloud 拡張の構成（Create new Redwood page/app for SaaS data、mashup SaaS and external data）」
• 変数のスコープと暗黙オブジェクト（$application・$flow・$page・$variables・$chain・$parameters）。
• アクション・チェーンはイベント・リスナーから起動。直列実行。複数チェーンはリスナーで並行起動。
• ライフサイクル・イベントの順序と用途（vbEnter で初期データ取得、vbBeforeExit で遷移の取り消し）。
• サービス接続の3つの作り方と、Metadata Retrieval Option の既定値（Copy minimal OpenAPI）。
• SDP の filterCriterion が q パラメータに変換されること。
• サービス接続はデータ・セキュリティを課さない。

公式ドキュメント

• What Are Variables and Types?（Building Responsive Applications with Visual Builder Studio）
• About the Action Chain Code
• Call REST（Oracle Visual Builder Page Model Reference）
• Service Data Provider Properties
• Define Events in Your Application
• Create a Service Connection from the Oracle Cloud Applications Catalog
• Add Service Connections to Your Extension
• What Is an Action Chain?（Extending Oracle Cloud Applications with VBS）

関連ページ

• REST API の基本
• 認証・認可（Basic・OAuth・JWT・統合ユーザー）
• Redwood デザインシステム
• Visual Builder Studio の基本
• 練習用 API プレイグラウンド