SAP CPIのバリューマッピングとコンテンツモディファイア基礎：設定・参照・障害対応

SAP CPI（Cloud Integration）では、送信元と送信先でコード体系が異なる場合にバリューマッピングを利用します。たとえば、送信元の会社コード 1000 を送信先の JP01 に変換する処理です。変換ルールをメッセージマッピングへ直接埋め込むのではなく、専用のマッピング情報として管理すると、複数のiFlowで同じ対応表を再利用できます。

この記事では、バリューマッピングの設計、コンテンツモディファイアでの参照、デプロイ後の確認、値が取得できない場合の切り分けを、実装担当者が扱いやすい順序で整理します。

01バリューマッピングの役割

バリューマッピングは、ある識別体系の値を別の識別体系へ変換するための対応表です。主な構成要素は、送信元の識別子、送信元の値、送信先の識別子、送信先の値です。

例として、次のような対応を登録します。

同じ値でも、業務項目によって意味が変わる可能性があります。そのため、識別子にはシステム名だけでなく、項目の意味や対象インターフェースが分かる名前を付けます。CompanyCode と Plant のように項目を分けると、誤った対応表の参照を防ぎやすくなります。

flowchart LR
    A[送信元コード] --> B[バリューマッピング]
    B --> C[送信先コード]
    D[コンテンツモディファイア] --> B
    B --> E[後続ステップ]

02バリューマッピングの設計

最初に、変換対象の業務項目、送信元の値、送信先の値、適用するiFlow、更新責任者を一覧化します。対応表を作成する前に、空値、未登録値、同じ送信元値に対する複数の送信先値を確認しておくことが重要です。

設計時には次の点を決めます。

• 識別子の命名規則
• 値の大文字・小文字の扱い
• 前後の空白を含むかどうか
• 未登録値をエラーにするか、既定値へ送るか
• 本番反映時の承認と変更履歴
• テスト用データと本番用データの管理単位

バリューマッピングは、固定値を数個置き換えるだけの処理に向いています。複雑な条件分岐、範囲判定、日付計算、複数項目の組み合わせが必要な場合は、メッセージマッピングやGroovyスクリプトなど、処理内容に合ったステップを選びます。

03コンテンツモディファイアからの参照

コンテンツモディファイアは、メッセージヘッダー、プロパティ、本文を設定するためのiFlowステップです。バリューマッピングの結果を後続処理で使う場合は、まずコンテンツモディファイアでプロパティへ格納し、そのプロパティをルーターやメッセージマッピングから参照する構成が扱いやすくなります。

基本的な流れは次のとおりです。

1. iFlowを開き、変換対象の前後にコンテンツモディファイアを配置する
2. バリューマッピングを参照する項目をプロパティまたはヘッダーに設定する
3. Source Agency、Source Value、Target Agencyを指定する
4. 取得した値を後続ステップの式やマッピングで利用する
5. 保存、デプロイ後に実データに近いメッセージで確認する

バリューマッピングの参照式は、利用する設定欄の種類とランタイムの仕様を確認して入力します。式を手入力する場合は、識別子のスペル、区切り文字、参照対象の値を正確にそろえます。画面上で候補選択が可能な場合は、候補から選択すると入力ミスを減らせます。

コンテンツモディファイアの設定例では、次のように役割を分けます。

業務データをヘッダーへ設定する場合は、接続先やログ出力に値が渡る範囲を確認します。後続の変換だけで必要な値は、通常プロパティへ置く方が意図を明確にできます。

04実装とテストの手順

実装では、最初から本番相当の大量データを使わず、登録済みの値、未登録の値、空値、特殊文字を含む値を個別にテストします。値の前後に空白がある入力も用意し、送信元システムから実際に届く文字列と一致するかを確認します。

テストケースの例は次のとおりです。

テスト時は、コンテンツモディファイア直後だけでなく、実際に値を使用するルーター、メッセージマッピング、受信アダプターまで確認します。途中でプロパティ名を変更すると後続ステップが値を取得できなくなるため、プロパティ名は設計書と一致させます。

運用開始後に対応表を変更する場合は、変更前後の値、適用日時、影響するiFlow、確認者を記録します。変更後は代表的な業務データで送受信を確認し、既存の変換結果が変わっていないかを監視します。

05障害の切り分け

バリューマッピングの結果が空になる場合は、最初に入力値が想定どおりか確認します。ログで入力値を確認できる場合は、前後の空白、大小文字、XML要素やJSONプロパティの取得位置を確認します。

次に、次の順序で調査します。

1. バリューマッピングが保存され、デプロイ済みであることを確認する
2. Source Agency、Source Value、Target Agencyの値を照合する
3. 入力値を固定値に置き換えて参照結果を確認する
4. コンテンツモディファイアのプロパティ名と後続参照名を照合する
5. iFlowのデプロイ状態と対象ランタイムを確認する
6. メッセージ処理ログで失敗ステップとエラー内容を確認する

設定変更後に古い結果が続く場合は、変更した成果物が対象テナントへデプロイされているか、実行中のiFlowが想定したバージョンかを確認します。複数環境を運用している場合は、開発、テスト、本番の対応表が同じ内容かを比較します。

メッセージ処理の確認には、SAP CPIのiFlow基礎で整理しているiFlowの構成要素と実行単位の理解が役立ちます。実行結果や失敗ステップの確認は、SAP CPIの監視とエラーハンドリング基礎の確認手順と合わせて行います。

06運用で守るポイント

対応表は小さな設定に見えても、複数のiFlowへ影響する共有資産です。登録値の追加や変更は、依頼内容、対象インターフェース、テスト結果を残してから反映します。

特に注意したいのは、既存値の上書きです。同じ識別子の組み合わせを変更すると、過去に正常だったメッセージの変換結果まで変わる可能性があります。新旧値を併存できる設計、適用開始日をデータ側で管理する設計、または段階的にiFlowを切り替える設計を検討します。

IDoc連携でコード変換を行う場合は、SAP CPIのIDoc連携基礎も参照し、IDocのセグメント項目とバリューマッピングの対象項目を対応付けます。値変換の責任範囲をiFlow、送信元、送信先のどこに置くかを決めると、障害時の調査範囲が明確になります。

07まとめ

バリューマッピングは、異なるシステム間のコード変換を再利用可能な対応表として管理する仕組みです。コンテンツモディファイアで参照結果をプロパティへ格納し、後続のルーターやメッセージマッピングで利用すると、処理の役割を分離できます。

運用では、識別子の命名、未登録値の扱い、デプロイ状態、実行ログ、変更履歴を一つずつ確認します。登録済み、未登録、空値、表記差を含むテストを先に用意すると、実データ投入後の予期しない変換エラーを減らせます。