Redwood ページの拡張（アプリケーション拡張・ページ拡張・ルール）

この章の結論

• Redwood ページは「Oracle が拡張可能にした領域」だけを VBS で変更できます。仕組みは ビジネス・ルール（項目・リージョンの表示制御と検証）、ルール・セット（動的テーブル・フォームのレイアウト）、ページ・プロパティ、動的コンテナ の4つです。
• ビジネス・ルールでは、項目ごとに Required・Hidden・Read Only・Value（既定値）を上書きできます。DFF・EFF の項目も同じように扱えます。
• ルールは画面上の並びの下から上へ（Default ルール → 組み込みルール → 拡張ルール）評価され、条件を満たした上のルールが優先されます。
• 入力チェックは Validate Field Values の検証ルールで作り、重大度は Error（修正必須）か Warning（注意のみ）を選びます。
• ルールは画面上の制御です。REST や FBDI からの登録には効かないため、必須の業務ルールは画面以外でも守られる仕組みと組み合わせます。

全体像

拡張の4つの仕組み

仕組み	制御するもの	効く範囲	開くボタン・エディタ
ビジネス・ルール	項目・リージョンの表示／必須／読取専用／既定値、検証メッセージ	ビジネス・オブジェクト単位（ページ内でその項目が出るすべてのフォーム）	Configure Fields and Regions、Validate Field Values
ルール・セット	動的テーブル・動的フォームに表示する項目と順序（レイアウト）	コンポーネント単位（フォームごとに個別に設定）	ルール・セット・エディタ
ページ・プロパティ	Oracle が用意したページの動作スイッチ（数値・文字列・ブール・配列）	ページ・フロー	ページ・プロパティの設定
動的コンテナ	決められた領域のセクションの並べ替え・追加	そのページだけ	コンテナとセクションの設定

ページを開いたときにどれが使えるかは、Oracle がそのページをどう作ったかで決まります。プロパティ・ペインに Business Rules ペインが出ればビジネス・ルール、レイアウトの一覧が出ればルール・セット、拡張できない旨の表示が出ればそのページは対象外です。

ビジネス・ルールとルール・セットの違いは「効く単位」です。ビジネス・ルールはオブジェクト単位なので、1つのルールでページ内の全フォームの同じ項目を隠せます。ルール・セットはフォームごとに設定する代わりに、条件に応じて項目の並び順を変えるような細かいレイアウト制御ができます。両方が同じ項目に影響する場合は、ルール・セットの変更が優先されます。Express モードのドキュメントは、両者を同じページで混在させるのは上級の手法で、一般には推奨しないとしています。

Express モードと Advanced モード

観点	Express モード	Advanced モード
想定利用者	機能管理者（業務設定の担当）	開発者
できること	ビジネス・ルール、検証ルール、ページ・プロパティ、コンテナとセクション、ルール・セットのルールとレイアウト	VBS のすべての機能（App UI の作成、変数、アクション・チェーン、サービス接続など）
対応状況（26C 時点）	HCM・SCM・調達の Redwood ページはこのモードのみ	HCM・SCM・調達ではサポート外

ビジネス・ルールの評価順

実行時、VBS はルールを下から上へ評価します。最初に Default ルール、次に組み込み（Built-in）ルール、最後に拡張ルールです。条件を満たしたルールのプロパティ値が順に適用されるため、一番上の有効なルールが、下のルールの設定を上書きします。

• Default ルール：標準の動作を表します。常に有効で、変更できず、条件がないため常に「真」として扱われます。
• 組み込みルール：Oracle（依存関係の拡張）が提供するルールで、読取専用です。一覧に Built-in と表示されます。
• 拡張ルール：自分で作るルールです。新しく作ると、拡張ルールの一覧の一番上に追加されます。右クリックの Move up／Move down で順番を変えます。
• 非アクティブにしたルール（名前に「(Inactive)」が付く）は評価されません。
• 項目に鍵のアイコンが付いている場合は、Default ルールがその値をロックしていて上書きできません。

例として、DFF「検収担当」（架空）を次の2つの拡張ルールで制御すると、結果は下の表のようになります。

並び（上から）	条件	Hidden	Required
拡張ルール B	営業単位が JP01 かつ金額が 100 万円以上	（指定なし）	Required
拡張ルール A	営業単位が JP01	Visible	（指定なし）
Default ルール	なし（常に真）	Hidden	Optional

• JP01・200 万円：Default（非表示）→ A（表示）→ B（必須）＝ 表示・必須
• JP01・50 万円：Default → A ＝ 表示・任意
• US01：Default のみ ＝ 非表示

設定・実装の手順

フォーム・ルールで表示・必須・読取専用を制御する

1. 対象の Redwood ページを開き、ユーザー名のメニュー（Settings and Actions）から Edit Page in Visual Builder Studio を選びます。
2. プロパティ・ペインの Configure Fields and Regions をクリックして、ビジネス・ルール・エディタを開きます。ボタンがなければ、そのページはまだこの機能に対応していません。
3. Form Rules の横の Create Rule アイコンをクリックし、Create Business Rule ダイアログを開きます。
4. Rule Type を選びます。通常は Regular です（If/else、Switch は入れ子のルール）。テンプレートがあれば Template から選べます。
5. ラベル（label）、ID、説明（description）を入力して Create をクリックします。
6. 条件を設定します（次の節）。
7. 項目を探し（Filter で絞り込み可）、Required・Hidden・Read Only・Value の列のダッシュ（-）をクリックして値を選びます。元に戻すときは Remove Override を使います。リージョンやオブジェクト型の項目は … > Set All Children で子項目にまとめて設定できます。
8. 変更は自動保存されます。ルールの Active トグルで有効・無効を切り替えます。

条件を設定する

1. ルールを選び、条件ペインの Edit で条件ビルダーを開きます。
2. 基準（Criterion） を一覧から選びます。独自の基準は追加できません。拡張の開発者が用意した基準は Object Context・Component Context の下にまとまっています。
3. 演算子 は基準の型で変わります。文字列では JavaScript の正規表現で判定する「match／not match」が使える場合があり、ブール型は equals だけです。
4. 値 を入力するか一覧から選びます。同じ型の別の項目と比較することもできます。
5. + Condition で条件を足します。既定では ALL（すべて真）で、ANY（いずれか真）に変えられます。Add Group でグループを作り、グループごとに all／any を設定できます。
6. 複雑な判定は Use Advanced Expression で式エディタを使います。
7. Done で閉じます（自動保存）。

ロールの条件では、値の欄に入力すると Fusion のジョブ・ロールと抽象ロールが最大 25 件候補表示されます。職務ロール（Duty Role）は候補に出ないため、名前を手入力します。また、同じ「国」などの条件でも、ページ（アクション）によって「処理対象の人」を指すか「画面を見ている人」を指すかが異なる場合があるため、製品ごとのドキュメントで意味を確認します。

条件には、項目の初期値（データベースに保存されている値）と現在値（ルールやユーザーが変更したキャッシュ上の値）の両方を使えます。たとえば勤務時間を 40 から 20 に変えた場合、初期値は 40、現在値は 20 です。

既定値を設定する

1. Fields and Regions エディタで対象項目を探し、Value 列のダッシュをクリックします。
2. Set Field Value で静的な値か式を入れます。Clear Field Value は、他のルール（Default ルールを含む）の既定値を消して空（null）にします。
3. 式は、参照している変数が変わるたびに再計算されます。

既定値は、ルールの条件を満たし、実行時にその項目が空のときに入ります。項目が編集可能ならユーザーは上書きできます。既定値を入れたうえで Read Only にする、という組み合わせもできます。

入力チェック（検証ルール）を作る

1. プロパティ・ペインの Business Rules の下にある Validate Field Values をクリックします。
2. 最初のルールなら + Validation、既存のルールがあれば Create Rule アイコン（Create Validation ダイアログ）を使います。
3. Regular を選び、ラベル・ID・説明を入れて Create をクリックします。
4. Edit で条件（エラーにしたい状況）を設定し、Done をクリックします。
5. + Message でメッセージを追加し、Summary（ダイアログのタイトル）と Detail（本文）を入れ、Severity を選び、Target Fields でメッセージを出す項目を選びます。
6. Live ビューで、ルールに引っかかる値を入れて確認します。

重大度	動き
Error	ユーザーは修正しないと送信できない
Warning	注意を促すが、操作は止めない

対象項目を1つ選ぶとメッセージはその項目の下にインライン表示されます。対象を選ばずフォームに複数の項目がある場合や、複数の項目を選んだ場合は、ダイアログで表示するためのメッセージ用コンポーネントがページに必要です。検証ルールは oj-dyn-form コンポーネントで描画されたフォームでのみ動き、古い oj-dynamic-form では動きません。

ルール・セットとレイアウト

ルール・セットを使うページでは、動的テーブル・フォームごとにレイアウトを選ぶルールを作ります。

• Layout（大文字）は拡張全体で使えるリソースで、データ・ソース（例：親オブジェクトや子オブジェクト）と項目を定義します。layout（小文字）は個々のルール・セットの中のレイアウトです。
• ルール・セットには、変更できない既定のレイアウト（default layout）があらかじめ用意されています。複製（Duplicate）して使います。既定のレイアウトは常に最後のルールで使われます。
• ルールは上から順に条件が確認され、どれにも当てはまらなければ既定のレイアウトになります。
• レイアウトでは項目の追加・削除・並べ替えのほか、項目ごとの Show Field 条件（既定は Always）、そのレイアウトだけに効く Read Only・Required を設定できます。全レイアウトに効かせたい場合は Fields エディタで設定します。
• Show Field の条件では、項目（$fields）、画面幅（$responsive。例：mdUp は 768 ピクセル以上で真）、ユーザー（$user。例：isAuthenticated、roles）を使えます。

ページ・プロパティと動的コンテナ

• ページ・プロパティは、Oracle がページに用意した設定値です（型は数値・文字列・ブール・配列）。たとえばパネルを隠す、タブを並べ替えるといった、ページ固有の動作を切り替えます。ルールの条件に応じて値を変えることもできます。
• 動的コンテナは、ページ内の決められた領域です。既存のセクションを並べ替えたり、自分のコンテンツを追加したりできます。動的コンテナはそのページの中だけに存在します。

拡張できる範囲と制約

• Designer で拡張可能と示された領域（青い枠）以外は変更できません。
• ビジネス・ルールはオブジェクト単位のため、同じページの別のフォームにも効きます。影響範囲を確認してから公開します。
• 必須（Required）にした項目は、隠す（Hidden）設定をしていても、既定値がなければユーザーが入力できるよう表示される場合があります。
• HCM・SCM・調達の Redwood 拡張ガイド（26C 時点）では、Advanced モードはサポート外です。また、Required＋Error Code（ツールチップの文言）の機能もこれらの製品ではサポートされず、上級の式で使える JavaScript は部分文字列の切り出しなどの変換に限られます。
• 同ガイドの例では、項目の書式（太字・色など）の変更はサポート外です。
• 拡張できる項目・ページ・プロパティはページごとに異なり、リリースで増えます。対象ページの製品ドキュメントと各リリースの新機能（What’s New）で確認します。

テストと公開

1. ポップアップ・ビューアで確認する：項目やリージョンにマウスを置くと情報ラベルが出ます。クリックすると、その項目に効いている有効なルールと Default ルールが一覧で表示されます。
2. Live ビュー・Preview で動かす：条件の真・偽の両方、対象ロールと対象外ロール、新規作成と既存データの更新を試します。
3. Share で共有する：プレビュー URL をレビュー担当に渡します。
4. Publish する：コメントを入れて公開します。レビューが必須の設定なら、コミット・メッセージ、マージ・リクエストの説明、レビュー担当を指定します。公開先は、作業中のインスタンス（通常はテスト用）です。
5. 他の環境へ配布する：Extension Lifecycle（Manage Extension Lifecycle ページ）の Deploy to Environment で本番などへ配布します。
6. 画面で確認する：最新の変更が見えないときは、サインアウトして再度サインインします。

コード例

公式ドキュメントの式の例

既定値の式（Set Field Value）と、検証メッセージの式です。メッセージに項目の値を含めるときは [[ ]] で囲み、文字列は引用符で囲んで + でつなぎます。

既定値の式（公式の例）

$fields.BudgetDetails.CurrencyCode.$value()

検証メッセージの式（公式の例を簡略化）

[[ 'Restricted feedback applies to ' + $fields.PersonName.$value() + '.' ]]

項目名（$fields. 以降）はページのビジネス・オブジェクトによって異なります。式エディタの (x) から変数を選ぶと、正しい参照を挿入できます。

ルール定義書（設計書）の例

VBS の内部形式ではなく、レビューと引き継ぎのための設計書の例です。

rule-spec.yaml（このサイト独自の設計書フォーマット・架空）

page: 購買依頼（Redwood）
rule:
  kind: form-rule            # Validate Field Values なら validation-rule
  label: JP01 検収担当必須
  id: jp01InspectorRequired
  position: 拡張ルールの最上位
  conditions:
    all:
      - criterion: 営業単位
        operator: equals
        value: JP01
  overrides:
    - field: 検収担当（DFF）
      hidden: Visible
      required: Required
tests:
  - JP01 で新規作成し、未入力で送信 → 必須エラー
  - US01 で新規作成 → 項目が表示されない
  - JP01 の既存データを開く → 項目が表示され、未入力なら必須エラー

評価順の考え方を確かめる

ビジネス・ルールの「下から上へ評価し、上のルールが上書きする」動きを、簡単なスクリプトで確かめます。VBS の実装ではなく、考え方を理解するためのシミュレーションです。

rule-cascade.js（node rule-cascade.js で実行）

// 配列の並び＝エディタ上の並び（上から下）。最後が Default ルール
const rules = [
  { label: 'B: JP01 高額は必須', active: true,
    when: (c) => c.bu === 'JP01' && c.amount >= 1000000, set: { required: true } },
  { label: 'A: JP01 は表示', active: true,
    when: (c) => c.bu === 'JP01', set: { hidden: false } },
  { label: 'Default', active: true,
    when: () => true, set: { hidden: true, required: false, readOnly: false } },
];

function evaluate(ctx) {
  const result = {};
  // 下（Default）から上へ。条件を満たしたルールの値で上書きしていく
  for (const rule of [...rules].reverse()) {
    if (rule.active && rule.when(ctx)) Object.assign(result, rule.set);
  }
  return result;
}

console.log(evaluate({ bu: 'JP01', amount: 2000000 })); // { hidden: false, required: true, readOnly: false }
console.log(evaluate({ bu: 'JP01', amount: 500000 }));  // { hidden: false, required: false, readOnly: false }
console.log(evaluate({ bu: 'US01', amount: 2000000 })); // { hidden: true, required: false, readOnly: false }

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

よくあるミス

• 一般的なルールを上に置いてしまう：上のルールが優先されるため、「全員に表示」のような広いルールを上に置くと、下の細かいルールが打ち消されます。新しいルールは一覧の一番上に追加される点にも注意します。
• オブジェクト単位で効くことを忘れる：別のフォームの同じ項目まで隠れてしまう。
• 画面のルールだけで必須を担保する：REST・FBDI・スプレッドシートからの登録には効きません。
• ロールの候補に職務ロールが出ないと悩む：職務ロールは手入力します。
• 古いフォームに検証ルールを作る：oj-dynamic-form のフォームでは検証メッセージが出ません。

• ルール名・ID に要件 ID（例：EXT-001）を含め、設計書と対応づけます。
• 1つのルールに多くの目的を詰め込まず、「表示」「必須」「既定値」「検証」を分けて作ると、切り分けやすくなります。
• 問い合わせ時は、ルールを非アクティブにして標準の動きで再現するかを確かめます。

試験対策ポイント

• 対応する試験：Redwood 模擬テスト の「VBS による Fusion Cloud 拡張の構成（Modify existing pages in Oracle SaaS using Visual Builder Studio）」
• 評価順：Default → 組み込み → 拡張（下から上）。上のルールが優先。Default ルールは常に有効・変更不可・条件なし。
• フォーム・ルールで上書きできるプロパティ：Required、Hidden、Read Only、Value。DFF・EFF も同様。
• ビジネス・ルール（オブジェクト単位・ページ全体）とルール・セット（コンポーネント単位・レイアウト）の違いと優先順位（ルール・セットが優先）。
• 検証ルールの重大度（Error／Warning）、Summary と Detail、Target Fields。
• 条件の既定は ALL、ANY に変更可。職務ロールは手入力。

公式ドキュメント

• Extending Oracle Cloud Applications in Visual Builder Studio Express Mode
• Understand What Will Be Shown at Runtime
• Override Field Properties in a Form
• Set a Default Value for a Field
• Display Messages in a Form
• What Are Dynamic Components?
• Create a Layout for a Rule Set
• Field and Region Display Control（HCM・SCM の Redwood 拡張ガイド）

関連ページ

• Visual Builder Studio の基本
• Visual Builder 開発の基礎
• フレックスフィールドと値セット
• VBS 演習：Redwood ページに項目とルールを追加する