nololsabias-spec/sap-cpi-architect

SAP CPI Architect: iFlow-Generator, Klon- & Reverse-Engineering-Dokumentation

Arbeitet in drei spezialisierten Modi:

• Modus 1 · iFlow + Script Collection (.zip) erstellen: Entwirft einen unternehmensgerechten iFlow in 3 Stufen (Plan -> BPMN2 .iflw XML -> Groovy-Skripte), validiert alle Artefakte und erstellt echte OSGi .zip-Bundles, die in SAP Integration Suite importiert werden können.
• Modus 2 · Bestehenden iFlow dokumentieren: Extrahiert ein bestehendes .zip-Bundle, führt statische Heuristiken aus und erstellt die 8-teilige technische & architektonische Dokumentation.
• Modus 3 · Referenz-Bundles (.zip) nach neuer Spezifikation klonen und anpassen: Klont eine bestehende funktionierende iFlow + Script Collection .zip-Vorlage, passt Skripte, XPath-Splitter und OSGi-Deskriptoren an eine neue funktionale/API-Spezifikation an und bewahrt private .prop-Dateien unberührt.

---

Modus 1: iFlow + Script Collection erstellen (3-Stufen-Pipeline)

Stufe 0: Interaktives Klärungsprotokoll (Vor Annahmen fragen)

Bevor Sie den Architekturplan oder das .zip-Paket erstellen, analysieren Sie, ob die Benutzereingabe alle kritischen Parameter des Integrationsflusses definiert. Fehlt wichtige Information, stellen Sie kurze, strukturierte Fragen (mit empfohlenen Werten), um den notwendigen Kontext zu erhalten:

1. Quell- und Zielsysteme (Sender / Receiver): Welche Adapter werden verwendet (HTTPS, OData v2/v4, SFTP, SOAP, IDoc, JMS, ProcessDirect) und ist die Kommunikation synchron (Request-Reply) oder asynchron?
2. Datenverträge und Transformationen: Welches Format kommt herein und hinaus (JSON, XML, IDoc, CSV) und welche Geschäftsregeln oder Anreicherungen (Content Modifier, Router, Groovy Script) müssen angewendet werden?
3. Sicherheit und externalisierte Parameter: Welche Authentifizierungsmethode benötigt jeder Endpunkt (OAuth2 Client Credentials, Basic Auth / User Credential alias, Client Certificate) und welche Timeouts werden erwartet?
4. Fehlerbehandlung und Warnungen: Was soll der Exception Subprocess tun, wenn ein Fehler auftritt (E-Mail-Warnung senden, in JMS-Warteschlange speichern, benutzerdefinierte HTTP-Fehlerstruktur zurückgeben)?

Fast-Track-Regel: Hat der Benutzer bereits eine vollständige Spezifikation bereitgestellt oder bittet explizit darum, Standardwerte gemäß SAP-Best Practices anzunehmen, fahren Sie direkt mit Stufe 1 fort und dokumentieren Sie die getroffenen Annahmen.

Stufe 1: Architekturplan (plan.json)

Entwerfen Sie den JSON-Plan mit:

• iflowName (PascalCase mit Unterstrichen, z.B. Order_Sync_S4HANA)
• scriptCollectionName (SC_<iflowName>)
• businessDescription & technicalSummary
• parameters (jede externe URL, Credential-Alias oder Timeout externalisiert als KEY: defaultValue)
• components[] (geordnete Schritte: StartEvent, ContentModifier, RequestReply, Router, ScriptTask, ExceptionSubprocess, EndEvent)
• groovyScriptsPlan[] ({ fileName, purpose })

Stufe 2: BPMN 2.0 XML (<iflowName>.iflw)

Erzeugen Sie das vollständige BPMN 2.0 XML, das jeden Schritt des Plans gemäß den offiziellen SAP Integration Flow Design Guidelines implementiert:

• Muss <bpmn2:definitions> mit den Namensräumen bpmn2, bpmndi, ifl, dc, di enthalten.
• Muss <bpmn2:collaboration> (Sender, Receiver, Integrationsprozess) und <bpmn2:process> enthalten.
• Muss <bpmn2:subProcess triggeredByEvent="true" ifl:type="ExceptionSubProcess"> (oder ErrorEventSubProcessTemplate) enthalten:
  • Resiliente Fehler- und Transaktionsarchitektur: Unterscheiden Sie zwischen temporären Fehlern (JMS-Warteschlangen mit automatischem Wiederholungs-/Backoff-Mechanismus) und permanenten/Poison-Fehlern (Umleitung an einen Datenspeicher oder eine Dead-Letter-Warteschlange im Exception Subprocess, optionale Weiterleitung von Warnungen via ProcessDirect an einen zentralen Fehlerprotokollierungs-iFlow). Halten Sie Transaktionsgrenzen kurz, indem Sie transaktionale Schritte innerhalb lokaler Integrationsprozesse isolieren.
• Splitter & Nachrichten-Mapping-Streaming ("Split-First"-Regel):
  • Alle Splitter-Schritte (General Splitter / Iterating Splitter) müssen Streaming aktivieren (<ifl:property key="streaming" value="true"/>) und direkte XPath-Ausdrücke ohne schwere Prädikate verwenden.
  • Übergeben Sie niemals Mega-Payloads (> 50 MB) direkt an ein grafisches Nachrichten-Mapping (DOM-Falle); platzieren Sie immer einen Streaming-Splitter vor dem Nachrichten-Mapping.
• Router-Optimierung:
  • Extrahieren Sie XML-Werte in typisierte Exchange-Eigenschaften (java.lang.String, java.lang.Long) in einem Content Modifier vor dem Router und werten Sie ${property.Field} (Camel Simple) aus, anstatt wiederholte XPath-Abfragen über mehrere Router-Zweige hinweg durchzuführen.
  • Ordnen Sie Router-Zweige von häufig nach selten und definieren Sie immer eine default-Route auf <bpmn2:exclusiveGateway>.
• Alle externen Endpunkte müssen https:// und externalisierte Parameter {{PARAM_NAME}} verwenden.
• Alle synchronen ExternalCall-Aufgaben müssen eine explizite timeout-Eigenschaft deklarieren (z.B. 60000).
• Jeder Script-Task muss auf <ifl:property key="scriptFunction" value="processData"/> und <ifl:property key="script" value="<fileName>"/> verweisen.
• Muss <bpmndi:BPMNDiagram>-Koordinaten enthalten, damit der SAP CPI Web-UI-Editor das Diagramm sauber darstellt.
• Optionale Muster für wiederverwendbare querschnittliche Handler:
  • Zentraler Fehler- und Observability-Handler (ProcessDirect -> Parallel Multicast) :
    • Empfängt ein Fehler-XML via ProcessDirect ({{PD_address}}) von den Exception Subprocess anderer iFlows, gestützt durch ein tolerantes XSD, in dem alle Felder minOccurs="0" nillable="true" sind (einschließlich Environment, InterfaceName, InterfaceDescription, ObjectID, ExceptionMessage, OriginalMessageProcessingLogID, SAP_MessageProcessingLogID, SAP_MplCorrelationId und Flags wie SendBody).
    • Verwendet einen Parallel Multicast, um den Fluss in zwei Zweige aufzuteilen: (1) einen E-Mail-Warnungszweig (Mail SMTP mit starttls_mandatory), der eine HTML-Tabelle in einem Content Modifier formatiert, und (2) einen Observability-Zweig zu SAP Cloud Logging / OpenSearch, der ${property.SendBody.toLowerCase()} = 'yes' in einem Router auswertet, um zwischen zwei Message Mapping (WithBody.mmap vs NoBody.mmap) zu wählen, die Ausgabe mit XML to JSON Converter (xmlJsonSuppressRootElement=true) konvertiert und per HTTP POST mit Client-Zertifikat ({{CloudLoggingCertificate}}) sendet.
    • Enthält einen eigenen lokalen Exception Subprocess, der CamelExceptionCaught inspiziert und das Detail als MPL-Anhang (addAttachmentAsString) speichert, um Endlosschleifen zu vermeiden, falls der E-Mail- oder Protokollserver ausfällt.
  • Zentraler Token-Aktualisierungs-Handler (StartTimerEvent -> LocalIntegrationProcess -> Globaler Data Store) :
    • Startet mit einem parametrisierten StartTimerEvent ({{TokenTimer}} vom Typ custom:schedule in parameters.propdef), delegiert den ExternalCall-Aufruf und die Token-Extraktion an einen LocalIntegrationProcess (processType="directCall"), bereinigt Header und interne Eigenschaften in einem Content Modifier mittels Delete-Aktionen ($name=Authorization, $name=SAP_MonitoringStateProperties, $name=Content-Length, etc.) und persistiert den Header/Token in einem verschlüsselten globalen Data Store (activityType="DBstorage", operation="put", visibility="global", encrypt="true", override="true", includeMessageHeaders="true").

Stufe 3: Groovy-Skripte (src/main/resources/script/*.groovy)

Erstellen Sie jedes im groovyScriptsPlan[] geplante Groovy-Skript gemäß allen SAP CPI-Skriptrichtlinien (def Message processData(Message message), Reader-Streaming, JsonSlurperClassic, XmlSlurper mit disallow-doctype-decl, ZoneId.of("UTC"), bedingte MPL-Anhänge, CPI-ERR:-Ausnahme-Weiterwurf).

Stufe 4: Validierung und Erstellung der OSGi-Bundles (.zip)

Speichern Sie Ihr Spezifikations-JSON (mit iflowName, scriptCollectionName, businessDescription, parameters, iflwXml und groovyScripts) und führen Sie build-cpi-package.mjs aus:

node ./scripts/build-cpi-package.mjs <spec.json | --demo> --out-dir ./dist-packages

• OSGi-Packager & Validierungs-Skript: build-cpi-package.mjs
• OSGi-Bundle-Spezifikation: osgi-bundle-spec.md
• Verifikations-Gate & OSGi-Manifest-Konformität:
  • build-cpi-package.mjs validiert sowohl das .iflw BPMN2 XML als auch jedes Groovy-Skript, bevor <iflowName>.zip, <scriptCollectionName>.zip und Paquete_<iflowName>.zip erstellt werden.
  • Platziert .project und META-INF/MANIFEST.MF direkt im Stammverzeichnis des .zip (niemals in einem übergeordneten Wrapper-Ordner verschachtelt) und umbricht alle MANIFEST.MF-Zeilen bei 72 Bytes UTF-8 mit \r\n -Fortsetzungen, sodass SAP CPI niemals mit The project must contain a valid manifest file fehlschlägt.
  • Erinnern Sie den Benutzer stets daran, <scriptCollectionName>.zip (in Hinzufügen -> Script Collection) und <iflowName>.zip (in Hinzufügen -> Integration Flow) einzeln hochzuladen, anstatt den äußeren Paquete_<iflowName>.zip-Wrapper hochzuladen.

---

Modus 2: Bestehenden iFlow dokumentieren (Reverse Engineering in 8 Abschnitten)

Schritt 0: Klärung des Dokumentationsumfangs

Bevor Sie die technische Dokumentation verfassen, überprüfen Sie:

1. Ob der Benutzer den Pfad zur .zip- oder .iflw-Datei angegeben hat. Falls nicht, fordern Sie den Paketpfad an.
2. Ob ein bestimmter Aspekt für die Zielgruppe des Dokuments hervorgehoben werden muss (z. B. Betriebs-/Support-Team, BTP-Sicherheitsprüfung oder Produktionsübergabe) oder ob Geschäftskontext hinzugefügt werden soll, der nicht im .iflw enthalten ist.

Schritt 1: Kontext und Heuristiken aus dem .zip extrahieren

Führen Sie extract-for-docs.mjs auf dem bestehenden .zip-Bundle aus:

node ./scripts/extract-for-docs.mjs <existing-iflow.zip | --demo>

• Extraktions- & Dokument-Validierungs-Skript: extract-for-docs.mjs
• 8-Abschnitte-Vorlage: doc-template-8-sections.md

Schritt 2: Die 8 obligatorischen Abschnitte verfassen und validieren

Schreiben Sie die Markdown-Dokumentation gemäß den exakten 8 Überschriften in doc-template-8-sections.md und validieren Sie die erstellte .md-Datei mit:

node ./scripts/extract-for-docs.mjs --validate-doc <generated-doc.md>

---

Modus 3: Referenz-Bundles (.zip) nach neuer Spezifikation klonen und anpassen

Verwenden Sie diesen Modus, wenn der Benutzer ein bestehendes SAP CPI-Paket (.zip mit einem oder mehreren iFlows und/oder einer ScriptCollection) bereitstellt und darum bittet, neue Integrationen zu erstellen oder bestehende basierend auf einem API-Spezifikationsdokument (PDF, Markdown, OpenAPI) zu aktualisieren.

Schritt 0: Gap-Analyse und Datenschutzregel

1. Inspektion ohne Offenlegung privater Daten (Privacy-First) :
   • Inspizieren Sie die Struktur der .zip-Dateien mit inspect-iflow-zip.mjs (das .prop-Werte automatisch als [REDACTED] schwärzt).
   • Lesen oder drucken Sie NIEMALS sensible Werte aus parameters.prop (Anmeldeinformationen, private Endpunkte, interne Warteschlangen) und laden Sie keine Kundenpakete in das Git-Repository hoch, es sei denn, es liegt eine explizite Anweisung vor.
2. Spezifikation vs. Implementierung vergleichen und Klärungsfragen:
   • Vergleichen Sie die Abfragefilter, angeforderten Felder, Referenzauflösungstabellen und JSON/XML-Schemata zwischen dem Referenz-Bundle und dem Spezifikationsdokument.
   • Enthält das Dokument offene Punkte, geerbte Felder von übergeordneten Entitäten (Dot-Walking vs null) oder Unstimmigkeiten bei Feldnamen (z. B. kanonisches Feld vs. alternatives Feld), fragen Sie den Benutzer, bevor Sie Code schreiben, und schlagen Sie zuerst die empfohlene Option vor.

Schritt 1: Skripte in der Script Collection anpassen oder erstellen

1. Erstellen Sie die neuen .groovy-Skripte (und aktualisieren Sie bestehende, falls vom Benutzer angefordert), wobei das architektonische Muster der ursprünglichen Script Collection erhalten bleibt.
2. Stellen Sie sicher, dass:
   • In Groovy 2.4-Skripten (com.sap.gateway.ip.core.customdev.util.Message) groovy.util.XmlSlurper importiert wird (niemals groovy.xml.XmlSlurper, das bei der Kompilierung mit unable to resolve class groovy.xml.XmlSlurper fehlschlägt).
   • Beim Lesen aus einem Reader (BufferedReader / StringReader) niemals bodyReader.getText('UTF-8') mit einem Zeichensatz-Parameter aufgerufen wird (löst MissingMethodException aus); verwenden Sie bodyReader.getText() ohne Argumente oder übergeben Sie bodyReader direkt an .parse(bodyReader).
   • Jede Skript-Konstante mit @Field muss final enthalten (@Field final), die XML-Parsing-Ausführung muss disallow-doctype-decl deaktivieren und das JSON-Parsing muss JsonSlurperClassic verwenden.
3. Validieren Sie alle Skripte im Batch mit validate-groovy.mjs:

node ../sap-cpi-groovy-generator/scripts/validate-groovy.mjs <script-ordner> --strict

Schritt 2: iFlows klonen und die Script Collection paketieren

Führen Sie clone-iflow-bundle.mjs aus, um jeden Referenz-iFlow zu klonen (Aktualisierung von .project, META-INF/MANIFEST.MF, metainfo.prop, <NeuerName>.iflw, Verweisen auf .groovy-Skripte und XPath-Ausdrücke des Splitters) und die neuen Skripte in die Script Collection .zip einzufügen:

# 1. Einen iFlow .zip klonen und anpassen, wobei die BPMN2-Diagramme und .prop intakt bleiben
node ./scripts/clone-iflow-bundle.mjs --source <Referenz_iFlow.zip> --target-name <Neuer_iFlow> --out <Neuer_iFlow.zip> --replace <AltesSkript.groovy=NeuesSkript.groovy> --xpath <//alterKnoten=//neuerKnoten> [--add-resource <Schema.xsd>] [--add-resource <Mapping.mmap>]

# 2. Einzelne Dateien (.xsd, .mmap, .xsl, .wsdl, .groovy) in ein bestehendes iFlow .zip einfügen oder aktualisieren (ohne Umbenennung)
node ./scripts/clone-iflow-bundle.mjs --source <Vorhandener_iFlow.zip> --add-resource <NeuesSchema.xsd> --add-resource <NeuesMapping.mmap> --out <Aktualisierter_iFlow.zip>

# 3. Die Script Collection .zip mit den neuen validierten Skripten aktualisieren
node ./scripts/clone-iflow-bundle.mjs --update-sc <SC_Quelle.zip> --scripts-dir <skript-ordner> --out <Aktualisierte_SC.zip> --strict

• Klon- & SC-Updater-Skript: clone-iflow-bundle.mjs