SAP CPI Architect: iFlow ジェネレーター、クローン & リバースエンジニアリング ドキュメント化ツール
3つの専門モードで動作します：
- モード1 · iFlow + スクリプトコレクション (
.zip) を生成: 3段階（計画 -> BPMN2.iflwXML -> Groovy スクリプト）でエンタープライズグレードのiFlowを設計し、すべての成果物を検証して、SAP Integration Suiteにインポート可能な実際のOSGi.zipバンドルを構築します。 - モード2 · 既存のiFlowを文書化: 既存の
.zipバンドルを抽出し、静的ヒューリスティックを実行して、8セクションの技術・アーキテクチャ文書を生成します。 - モード3 · リファレンスバンドル (
.zip) を新しい仕様に基づいてクローン＆適応: 既存の動作するiFlow + スクリプトコレクション.zipテンプレートをクローンし、スクリプト、XPathスプリッター、OSGi記述子を新しい機能/API仕様に適応し、プライベートな.propファイルはそのまま保持します。
モード1: iFlow + スクリプトコレクションを生成（3段階パイプライン）
ステージ0: インタラクティブな明確化プロトコル（前提とする前に質問する）
アーキテクチャ計画や .zip パッケージを生成する前に、ユーザーのプロンプトが統合フローのすべての重要なパラメーターを定義しているかどうかを分析してください。重要な情報が不足している場合は、推奨値を提案しながら、簡潔で構造化された質問を行い、必要なコンテキストを取得します：
- 送信元システムと宛先システム（Sender / Receiver）：どのアダプターを使用するか（HTTPS、OData v2/v4、SFTP、SOAP、IDoc、JMS、ProcessDirect）、および通信が同期（
Request-Reply）か非同期か？ - データ契約と変換：どのフォーマットで出入力するか（JSON、XML、IDoc、CSV）、およびどのビジネスルールやエンリッチメント（
Content Modifier、Router、Groovy Script）を適用する必要があるか？ - セキュリティと外部化パラメーター：各エンドポイントにはどの認証方法が必要か（OAuth2 Client Credentials、Basic Auth / User Credential alias、Client Certificate）、およびどのタイムアウトが想定されるか？
- エラー管理とアラート：
Exception Subprocessは障害発生時に何を行うべきか（メールでアラートを送信、JMSキューに保存、カスタムHTTPエラー構造を返す）？
快速ルール: ユーザーがすでに完全な仕様を提供している場合、またはSAPのベストプラクティスのデフォルト値を想定するよう明示的に要求した場合は、想定した前提条件を文書化して直接ステージ1に進みます。
ステージ1: アーキテクチャ計画 (plan.json)
以下の内容を含むJSON計画を設計します：
iflowName（PascalCase、アンダースコア区切り、例：Order_Sync_S4HANA）scriptCollectionName（SC_<iflowName>）businessDescriptionとtechnicalSummaryparameters（すべての外部URL、クレデンシャルエイリアス、またはタイムアウトをKEY: defaultValueとして外部化）components[]（順序付けられたステップ：StartEvent、ContentModifier、RequestReply、Router、ScriptTask、ExceptionSubprocess、EndEvent）groovyScriptsPlan[]（{ fileName, purpose }）
ステージ2: BPMN 2.0 XML (<iflowName>.iflw)
SAP公式の統合フロー設計ガイドラインに従い、計画のすべてのステップを実装する完全なBPMN 2.0 XMLを生成します：
- 名前空間
bpmn2、bpmndi、ifl、dc、diを含む<bpmn2:definitions>が必要です。 <bpmn2:collaboration>（Sender、Receiver、Integration Process）および<bpmn2:process>が必要です。<bpmn2:subProcess triggeredByEvent="true" ifl:type="ExceptionSubProcess">（またはErrorEventSubProcessTemplate）が必要です：- 回復力のあるエラー＆トランザクションアーキテクチャ: 一時的なエラー（自動再試行/バックオフ付きJMSキューを使用）と永続的/有害なエラー（Exception Subprocess内のデータストアまたはデッドレターキューにルーティングし、必要に応じて
ProcessDirectを介して中央エラーロギングiFlowにアラートを転送）を区別します。トランザクション境界を短く保つために、トランザクションステップをローカル統合プロセス内に分離します。
- 回復力のあるエラー＆トランザクションアーキテクチャ: 一時的なエラー（自動再試行/バックオフ付きJMSキューを使用）と永続的/有害なエラー（Exception Subprocess内のデータストアまたはデッドレターキューにルーティングし、必要に応じて
- スプリッター＆メッセージマッピングストリーミング（"Split-First" ルール）:
- すべての
Splitterステップ（General Splitter/Iterating Splitter）はストリーミングを有効にする必要があります（<ifl:property key="streaming" value="true"/>）。また、重い述語のない直接的なXPath式を使用します。 - 巨大なペイロード（> 50 MB）をグラフィカルなメッセージマッピング（DOMトラップ）に直接渡さないでください。メッセージマッピングの前にストリーミング
Splitterを常に配置します。
- すべての
- ルーター最適化:
- XML値を
Content Modifierで型付きExchangeプロパティ（java.lang.String、java.lang.Long）に抽出してからRouterの前に配置し、複数のルーターブランチ間で繰り返しXPathを評価する代わりに${property.Field}（Camel Simple）を評価します。 - ルーターブランチを最も頻繁に発生するものから最も頻度の低いものの順に並べ、常に
<bpmn2:exclusiveGateway>にdefaultルートを定義します。
- XML値を
- すべての外部エンドポイントは
https://を使用し、外部化パラメーター{{PARAM_NAME}}を使用する必要があります。 - すべての同期
ExternalCallタスクは、明示的なtimeoutプロパティ（例：60000）を宣言する必要があります。 - すべてのスクリプトタスクは、
<ifl:property key="scriptFunction" value="processData"/>および<ifl:property key="script" value="<fileName>"/>を参照する必要があります。 - SAP CPI Web UIエディターがダイアグラムをきれいにレンダリングするために、
<bpmndi:BPMNDiagram>座標を含める必要があります。 - 再利用可能な横断的ハンドラーのオプションパターン:
- 集中エラー＆可観測性ハンドラー（
ProcessDirect->Parallel Multicast）:- 他のiFlowの
Exception SubprocessからProcessDirect（{{PD_address}}）経由でエラーXMLエンベロープを受信します。すべてのフィールドがminOccurs="0" nillable="true"（Environment、InterfaceName、InterfaceDescription、ObjectID、ExceptionMessage、OriginalMessageProcessingLogID、SAP_MessageProcessingLogID、SAP_MplCorrelationId、およびSendBodyなどのフラグを含む）である寛容なXSDによってバックアップされます。 Parallel Multicastを使用してフローを2つのブランチに分割します：(1)Content ModifierでHTMLテーブルをフォーマットするメールアラートブランチ（MailSMTP、starttls_mandatory）、および(2) SAP Cloud Logging / OpenSearch への可観測性ブランチ。Routerで${property.SendBody.toLowerCase()} = 'yes'を評価して2つのMessage Mapping（WithBody.mmapvsNoBody.mmap）を選択し、出力をXML to JSON Converter（xmlJsonSuppressRootElement=true）で変換し、クライアント証明書（{{CloudLoggingCertificate}}）を使用してHTTPPOSTで送信します。- メールサーバーまたはログサーバーが失敗した場合の無限ループを防ぐために、
CamelExceptionCaughtを検査し、詳細をMPL添付ファイル（addAttachmentAsString）として保存する独自のローカルException Subprocessを含めます。
- 他のiFlowの
- 集中トークンリフレッシュハンドラー（
StartTimerEvent->LocalIntegrationProcess-> グローバルData Store）:- パラメーター化された
StartTimerEvent（parameters.propdef内のcustom:scheduleタイプの{{TokenTimer}}）で開始し、ExternalCall呼び出しとトークン抽出をLocalIntegrationProcess（processType="directCall"）に委任し、Content ModifierでDeleteアクション（$name=Authorization、$name=SAP_MonitoringStateProperties、$name=Content-Lengthなど）を使用して内部ヘッダーとプロパティをクリーンアップし、ヘッダー/トークンを暗号化されたグローバルデータストア（activityType="DBstorage"、operation="put"、visibility="global"、encrypt="true"、override="true"、includeMessageHeaders="true"）に永続化します。
- パラメーター化された
- 集中エラー＆可観測性ハンドラー（
ステージ3: Groovyスクリプト（src/main/resources/script/*.groovy）
すべてのSAP CPIスクリプティングガイドライン（def Message processData(Message message)、Reader ストリーミング、JsonSlurperClassic、XmlSlurper（disallow-doctype-decl 付き）、ZoneId.of("UTC")、条件付きMPL添付ファイル、CPI-ERR: 例外再スロー）に従い、groovyScriptsPlan[] で計画された各Groovyスクリプトを作成します。
ステージ4: OSGiバンドル (.zip) の検証と構築
iflowName、scriptCollectionName、businessDescription、parameters、iflwXml、groovyScripts を含む仕様JSONを保存し、build-cpi-package.mjs を実行します：
node ./scripts/build-cpi-package.mjs <spec.json | --demo> --out-dir ./dist-packages
- OSGiパッケージャー＆バリデータースクリプト: build-cpi-package.mjs
- OSGiバンドル仕様: osgi-bundle-spec.md
- 検証ゲート＆OSGiマニフェスト準拠:
build-cpi-package.mjsは、<iflowName>.zip、<scriptCollectionName>.zip、およびPaquete_<iflowName>.zipを生成する前に、.iflwBPMN2 XMLとすべてのGroovyスクリプトの両方を検証します。.projectおよびMETA-INF/MANIFEST.MFを.zipのルートに直接 配置し（トップレベルのラッパーフォルダー内にネストしない）、すべてのMANIFEST.MF行を 72バイトUTF-8 でラップし、\r\nの継続行を使用して、SAP CPIがThe project must contain a valid manifest fileで失敗しないようにします。- ユーザーには、外側の
Paquete_<iflowName>.zipラッパーをアップロードするのではなく、<scriptCollectionName>.zip（Add -> Script Collection）と<iflowName>.zip（Add -> Integration Flow）を個別にアップロードするように常に注意してください。
モード2: 既存のiFlowを文書化（8セクションのリバースエンジニアリング）
ステップ0: 文書化範囲の明確化
技術文書を作成する前に、以下を確認します：
- ユーザーが
.zipファイルまたは.iflwファイルへのパスを提供しているかどうか。提供されていない場合は、パッケージへのパスを尋ねます。 - 文書の対象読者（例：運用/サポートチーム、BTPセキュリティ監査、または本番移行）のために特定の側面を強調する必要があるか、または
.iflw内に記載されていないビジネスコンテキストを追加する必要があるか。
ステップ1: .zip からコンテキストとヒューリスティックを抽出
既存の .zip バンドルに対して extract-for-docs.mjs を実行します：
node ./scripts/extract-for-docs.mjs <existing-iflow.zip | --demo>
- 抽出＆文書バリデータースクリプト: extract-for-docs.mjs
- 8セクションテンプレート: doc-template-8-sections.md
ステップ2: 必須の8セクションを作成して検証
doc-template-8-sections.md の正確な8つの見出しに従ってMarkdown文書を作成し、生成された .md ファイルを以下で検証します：
node ./scripts/extract-for-docs.mjs --validate-doc <generated-doc.md>
モード3: リファレンスバンドル (.zip) を新しい仕様に基づいてクローン＆適応
ユーザーが既存のSAP CPIパッケージ（1つ以上のiFlowおよび/または ScriptCollection を含む .zip）を提供し、API仕様書（PDF、Markdown、OpenAPI）に基づいて新しい統合を作成したり、既存の統合を更新したりするよう要求した場合にこのモードを使用します。
ステップ0: ギャップ分析とプライバシールール
- プライバシーファースト：機密データを公開しない検査:
inspect-iflow-zip.mjsで.zipの構造を検査します（.propの値を自動的に[REDACTED]として編集します）。- 決して
parameters.propの機密値（クレデンシャル、プライベートエンドポイント、内部キュー）を読み取ったり印刷したりせず、明示的な指示がない限り、クライアントパッケージをGitリポジトリにアップロードしないでください。
- 仕様と実装の対比と明確化の質問:
- リファレンスバンドルと仕様書の間で、クエリフィルター、要求フィールド、参照解決テーブル、JSON/XMLスキーマを比較します。
- 文書に未解決の点、親エンティティから継承されたフィールド（ドットウォーキング vs
null）、またはフィールド名の不一致（例：正規フィールド vs 代替フィールド）がある場合は、コードを書く前にユーザーに質問し、最初に推奨オプションを提案します。
ステップ1: スクリプトコレクション内のスクリプトを適応または作成
- 元のスクリプトコレクションのアーキテクチャパターンを維持しながら、新しい
.groovyスクリプトを作成し（ユーザーが要求した場合は既存のスクリプトを更新します）。 - 以下を確認します：
- Groovy 2.4スクリプト（
com.sap.gateway.ip.core.customdev.util.Message）では、groovy.util.XmlSlurperをインポートします（groovy.xml.XmlSlurperはunable to resolve class groovy.xml.XmlSlurperでコンパイルに失敗するため、決して使用しないでください）。 Reader（BufferedReader/StringReader）から読み取る場合、決してbodyReader.getText('UTF-8')を文字セットパラメーター付きで呼び出さないでください（MissingMethodExceptionをスローします）。引数なし でbodyReader.getText()を使用するか、bodyReaderを直接.parse(bodyReader)に渡します。- スクリプトレベルのすべての定数に
@Fieldを使用する場合はfinalを含め（@Field final）、XMLパースではdisallow-doctype-declを無効にし、JSONパースではJsonSlurperClassicを使用します。
- Groovy 2.4スクリプト（
validate-groovy.mjsですべてのスクリプトを一括検証します：
node ../sap-cpi-groovy-generator/scripts/validate-groovy.mjs <scripts-folder> --strict
ステップ2: iFlowをクローンし、スクリプトコレクションをパッケージ化
clone-iflow-bundle.mjs を実行して、各リファレンスiFlowをクローンし（.project、META-INF/MANIFEST.MF、metainfo.prop、<NewName>.iflw、.groovy スクリプトへの参照、スプリッターのXPath式を更新）、新しいスクリプトをスクリプトコレクション .zip に注入します：
# 1. BPMN2図と.propをそのまま維持しながらiFlow .zipをクローン＆適応
node ./scripts/clone-iflow-bundle.mjs --source <Reference_iFlow.zip> --target-name <New_iFlow> --out <New_iFlow.zip> --replace <OldScript.groovy=NewScript.groovy> --xpath <//oldNode=//newNode> [--add-resource <Schema.xsd>] [--add-resource <Mapping.mmap>]
# 2. 個別ファイル（.xsd、.mmap、.xsl、.wsdl、.groovy）を既存のiFlow .zipに注入または更新（名前は変更しない）
node ./scripts/clone-iflow-bundle.mjs --source <Existing_iFlow.zip> --add-resource <NewSchema.xsd> --add-resource <NewMapping.mmap> --out <Updated_iFlow.zip>
# 3. 検証済みの新しいスクリプトでスクリプトコレクション .zip を更新
node ./scripts/clone-iflow-bundle.mjs --update-sc <SC_Original.zip> --scripts-dir <scripts-folder> --out <SC_Updated.zip> --strict
- クローナー＆SC更新スクリプト: clone-iflow-bundle.mjs
- パラメーター正確性仕様: parameter-accuracy-spec.md
ステップ3: パラメーターの正確性検証と最終文書化
- スクリプトコレクション
.zip内のスクリプトが参照するすべてのプロパティキーが、iFlow.zip内のparameters.propに 正確に 存在することを検証します（大文字小文字を区別、project_scoped=falseを尊重）。 - 必要に応じて
parameters.propを生成または更新します（元のプロジェクトスコープ設定を維持）。 - 新しいiFlowの
businessDescriptionとセクション5（「外部パラメーター」）を更新し、新しいparameters.propキーを反映したplan.jsonで文書化します。
最終注意事項
- 重要: このスキルは
.zipバンドル（Paquete_<name>.zipラッパー）を作成し、その中に<name>.iflwiFlowバンドルとSC_<name>.zipスクリプトコレクションバンドルを含めます。ユーザーは常にPaquete_<name>.zipラッパー自体ではなく、これら2つの内部バンドルを個別に SAP Integration Suite / Cloud Integration Web UIにアップロードする必要があります。 - 実装の詳細（OSGiバンドルレイアウト、MANIFEST.MF要件、BPMN2スキーマテンプレートなど）については、references/ フォルダー内の参照ドキュメントを参照してください。