SAP連携（PI/PO/CPI）
SAP CPI メッセージマッピング基礎：グラフィカルマッピングと関数の実務
SAP Cloud Integrationでメッセージマッピングを設計・実装・テストするための基礎を、グラフィカルマッピング、コンテキスト、関数、条件分岐、エラー調査の流れに沿って解説します。
SAP Cloud Integration（SAP CPI）のメッセージマッピングは、送信元メッセージの構造や値を、受信側システムが要求する形式へ変換するための中核機能です。単純な項目コピーだけでなく、階層の繰り返し、条件分岐、コード変換、日付や文字列の加工まで扱います。
実装を安定させるには、マッピング画面で線をつなぐ作業から始めず、送信元・受信先の構造、必須項目、繰り返し単位、空値の扱いを先に整理します。この記事では、iFlowの中でメッセージマッピングを配置し、テストから運用時の切り分けまで進める手順を説明します。
メッセージマッピングの役割
メッセージマッピングは、XMLやJSONなどのメッセージ構造を別の構造へ変換する処理です。たとえば、送信元のCustomerIDを受信先のBusinessPartnerへ変換し、住所や明細を受信側の階層へ配置します。
マッピングの責任範囲は、主に次の3つです。
- 項目と階層の対応付け
- 値の変換、補完、条件分岐
- 繰り返し要素やコンテキストの調整
通信先の認証、接続先URL、再送、監視は別の設定で管理します。iFlow全体の構成を確認したい場合は、SAP CPI iFlowの基礎も参照してください。
設計前に整理する入出力
メッセージマッピングを作成する前に、送信元と受信先のスキーマを用意します。XMLであればXSD、JSONであればサンプルペイロードや構造定義を確認し、実際のデータに存在する繰り返しや任意項目を把握します。
最低限、次の項目を表にまとめると作業が進めやすくなります。
| 確認項目 | 確認内容 |
|---|---|
| 業務キー | 受注番号、取引先コードなど、送受信で同じ意味を持つ値 |
| 必須項目 | 受信側で欠落するとエラーになる項目 |
| 繰り返し単位 | 明細、住所、連絡先などの繰り返し範囲 |
| コード値 | 送信元と受信先で異なる区分値 |
| 空値 | 空文字、未設定、既定値のどれとして扱うか |
| データ型 | 文字列、日付、数値、Booleanなどの違い |
送信元の項目名と受信先の項目名が似ていても、意味や繰り返し単位が一致するとは限りません。項目名ではなく、業務上の意味と親子関係で対応を決めます。
グラフィカルマッピングの基本操作
SAP CPIのグラフィカルマッピングでは、ソース側とターゲット側の要素を表示し、対応する要素を接続します。単純な1対1の項目であれば、ソース要素からターゲット要素へ接続するだけで値を渡せます。
実装は次の順序で進めると、後からの修正を抑えられます。
- ルート要素と主要な親階層を確認する。
- 受信側の必須要素を先に配置する。
- 業務キーや識別子など、追跡に使う項目を接続する。
- 明細や子要素の繰り返し関係を設定する。
- 固定値、条件、関数を追加する。
- 任意項目と空値の動作を確認する。
- サンプルデータで出力全体を検証する。
複数のソース要素を1つのターゲットへ集約する場合は、連結、条件、コンテキストの境界を明確にします。親要素が異なる値を単純に接続すると、意図しない組み合わせが生成されることがあります。
マッピング関数の使い分け
関数は、入力値を受信側の形式へ変換するために使います。関数を追加する前に、変換が本当にマッピング層の責任かを確認します。業務ルールそのものを関数へ詰め込みすぎると、テストと保守が難しくなります。
よく使う処理には、次のようなものがあります。
- 文字列処理：連結、部分文字列、前後の空白除去
- 条件処理：入力値に応じた既定値や出力先の切り替え
- 数値処理：単位変換、丸め、数値形式の整形
- 日付処理：日付形式の変換、タイムゾーンを考慮した整形
- 存在判定：入力が存在するときだけターゲットへ値を生成
- コード変換：送信元の区分値を受信先のコードへ変換
複数の関数を連結する場合は、途中結果を追跡できる構成にします。たとえば、空白除去、コード変換、既定値設定を1つの複雑な式にまとめず、処理の意味が分かる単位に分けます。
コンテキストと繰り返しの扱い
マッピングで最も問題になりやすいのが、繰り返し要素のコンテキストです。受注明細のように複数の要素を持つ構造では、どの親要素を基準に値を組み合わせるかを正しく設定する必要があります。
たとえば、送信元に注文ヘッダーと複数の明細がある場合、ヘッダーの注文番号を各明細へ繰り返し出力する処理と、明細同士を同じインデックスで対応付ける処理は異なります。単純な接続で解決できないときは、コンテキストの変更、削除、複製に関係する関数を使って繰り返し範囲を調整します。
確認では、明細が1件だけのデータだけでなく、0件、1件、複数件の3パターンを用意します。明細が複数件あるときに、ヘッダーが重複しすぎたり、明細の組み合わせが増えたりしないかを確認します。
条件分岐と既定値
受信側の項目を常に出力するのか、条件を満たす場合だけ出力するのかを設計段階で決めます。空文字を出力することと、要素自体を出力しないことは、受信側の検証結果が異なる場合があります。
条件分岐では、次の観点を確認します。
- 入力が存在しない場合の結果
- 入力が空文字の場合の結果
0やfalseを未設定として扱わないこと- 条件に該当しない場合の既定値
- 必須項目を生成できない場合のエラー処理
固定値は、環境や業務ルールに依存しない値に限定します。環境ごとに変わる値は、外部化パラメータやセキュリティアーティファクトなど、適切な設定管理の仕組みで扱います。認証や接続設定の整理には、SAP CPIアダプタ種別の比較が役立ちます。
テストデータの作り方
テストは、正常系の代表データだけで完了させません。入力値の境界と、実際に発生する欠損や繰り返しを含めたデータを準備します。
| テストケース | 確認する内容 |
|---|---|
| 標準ケース | 通常の項目、明細、コード値が正しく変換されるか |
| 任意項目なし | 省略された要素が受信側の期待どおりになるか |
| 複数明細 | 繰り返しと親子関係が保たれるか |
| 空文字 | 空文字が要素、省略、既定値のどれになるか |
| 特殊文字 | XMLやJSONのエスケープが正しく処理されるか |
| 長さ超過 | 受信側の最大長を超えた値をどう扱うか |
| 不正コード | 変換表に存在しない値を検出できるか |
SAP CPIのメッセージマッピングでは、入力と出力を並べて確認し、期待結果をテストケースごとに保存します。テストデータには業務キーを含め、実行後のメッセージ追跡と照合できるようにします。
デプロイ後のエラー切り分け
デプロイ後にエラーが発生した場合は、マッピング定義、入力ペイロード、受信側の検証、接続処理を分けて調査します。最初にメッセージ処理ログで失敗ステップとエラー内容を確認し、マッピングステップで停止しているかを特定します。
マッピング付近で確認する順序は次のとおりです。
- 実際に受信したペイロードが想定スキーマと一致しているか確認する。
- 必須要素や名前空間が存在するか確認する。
- 入力が空の場合の条件分岐を確認する。
- 繰り返し要素のコンテキストを確認する。
- 関数の入力型と出力型を確認する。
- 生成された出力を受信側の仕様と照合する。
- マッピング後のアダプタ処理や受信側エラーを分離する。
運用では、ペイロードの機密情報をログへ残しすぎないことが重要です。監視設計と再処理の考え方は、SAP CPI監視とエラーハンドリングの基礎で確認できます。
保守しやすいマッピングの設計
マッピングは、作成者だけが理解できる構成にしないことが大切です。関数名やグループ化を業務上の意味に合わせ、複雑な変換には設計書やテストケースへの参照を残します。
保守性を高める実務上のポイントは次のとおりです。
- 1つのマッピングに過剰な業務ルールを集約しない
- コード変換の根拠と管理者を明確にする
- 固定値の用途をコメントや設計資料で残す
- 入力と出力のサンプルをバージョン管理する
- 変更前後で必須項目と繰り返し結果を比較する
- 本番データをそのままテスト資材として共有しない
大規模な連携では、マッピングの変更だけでなく、送信側のスキーマ、受信側のAPI、アダプタ、例外処理も影響範囲に含めます。連携全体の位置付けを整理する場合は、SAP連携（PI・PO・CPI）の全体像も参照してください。
実装前後のチェックリスト
最後に、実装前後で次の項目を確認します。
- 入出力スキーマと名前空間を確定した
- 必須項目と任意項目を分類した
- 繰り返し単位とコンテキストを確認した
- コード変換と既定値のルールを決めた
- 0件、1件、複数件のテストを実施した
- 空文字、欠損、不正コードを検証した
- 受信側の形式とデータ型を確認した
- エラー時のログ、再処理、通知方法を確認した
- 変更内容とテスト結果を記録した
メッセージマッピングは、線を接続して出力が表示されれば完了する処理ではありません。入出力の契約、繰り返しの意味、空値の扱い、運用時の追跡方法まで一体として設計すると、連携障害の調査時間を短縮できます。