nololsabias-spec/sap-cpi-architect

Architecte SAP CPI : Générateur, Cloneur & Documenteur par Rétro-Ingénierie d'iFlow

Fonctionne selon trois modes spécialisés :

• Mode 1 · Générer iFlow + Script Collection (.zip) : Conçoit un iFlow de qualité professionnelle en 3 étapes (Plan -> XML BPMN2 .iflw -> Scripts Groovy), valide tous les artefacts et construit des bundles OSGi .zip réels importables dans SAP Integration Suite.
• Mode 2 · Documenter un iFlow Existant : Extrait un bundle .zip existant, exécute des heuristiques statiques et génère la documentation technique et architecturale en 8 sections.
• Mode 3 · Cloner et Adapter des Bundles de Référence (.zip) selon une Nouvelle Spécification : Clone un modèle d'iFlow + Script Collection .zip existant et fonctionnel, adapte les scripts, les séparateurs XPath et les descripteurs OSGi à une nouvelle spécification fonctionnelle/API, et préserve les fichiers .prop privés intacts.

---

Mode 1 : Générer iFlow + Script Collection (Pipeline en 3 Étapes)

Étape 0 : Protocole de Clarification Interactive (Demander avant de Présumer)

Avant de générer le plan architectural ou le package .zip, analysez si l'invite de l'utilisateur définit tous les paramètres critiques du flux d'intégration. Si des informations clés manquent, posez des questions brèves et structurées (en proposant des valeurs recommandées) pour obtenir le contexte nécessaire :

1. Systèmes Source et Cible (Expéditeur / Récepteur) : Quels adaptateurs utilisent-ils (HTTPS, OData v2/v4, SFTP, SOAP, IDoc, JMS, ProcessDirect) et la communication est-elle synchrone (Request-Reply) ou asynchrone ?
2. Contrats de Données et Transformations : Quel format entre et sort (JSON, XML, IDoc, CSV) et quelles règles métier ou enrichissements (Content Modifier, Router, Groovy Script) doivent être appliqués ?
3. Sécurité et Paramètres Externalisés : Quelle méthode d'authentification chaque point de terminaison nécessite-t-il (OAuth2 Client Credentials, Basic Auth / alias d'identifiant utilisateur, certificat client) et quels délais d'attente sont attendus ?
4. Gestion des Erreurs et Alertes : Que doit faire le Exception Subprocess en cas d'échec (envoyer une alerte par e-mail, enregistrer dans une file d'attente JMS, renvoyer une structure d'erreur HTTP personnalisée) ?

Règle de Voie Rapide : Si l'utilisateur a déjà fourni une spécification complète ou demande explicitement de supposer les valeurs par défaut des meilleures pratiques SAP, passez directement à l'Étape 1 en documentant les hypothèses retenues.

Étape 1 : Plan Architectural (plan.json)

Concevez le plan JSON contenant :

• iflowName (PascalCase avec underscores, ex., Order_Sync_S4HANA)
• scriptCollectionName (SC_<iflowName>)
• businessDescription & technicalSummary
• parameters (chaque URL externe, alias d'identifiant ou délai d'attente externalisé comme KEY: defaultValue)
• components[] (étapes ordonnées : StartEvent, ContentModifier, RequestReply, Router, ScriptTask, ExceptionSubprocess, EndEvent)
• groovyScriptsPlan[] ({ fileName, purpose })

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

Générez le XML BPMN 2.0 complet implémentant chaque étape du plan en suivant les Directives de Conception de Flux d'Intégration officielles de SAP :

• Doit inclure <bpmn2:definitions> avec les espaces de noms bpmn2, bpmndi, ifl, dc, di.
• Doit inclure <bpmn2:collaboration> (Expéditeur, Récepteur, Processus d'Intégration) et <bpmn2:process>.
• Doit inclure <bpmn2:subProcess triggeredByEvent="true" ifl:type="ExceptionSubProcess"> (ou ErrorEventSubProcessTemplate) :
  • Architecture d'Erreur et de Transaction Résiliente : Faites la différence entre les erreurs transitoires (utilisez des files d'attente JMS avec réessai automatique/backoff) et les erreurs persistantes/empoisonnées (acheminez vers un Data Store ou une file d'attente de lettres mortes dans le sous-processus d'exception, et éventuellement transférez les alertes via ProcessDirect vers un iFlow central de journalisation des erreurs). Gardez les limites de transaction courtes en isolant les étapes transactionnelles à l'intérieur de processus d'intégration locaux.
• Règle de "Split en Premier" pour le Splitter et le Message Mapping en Streaming :
  • Toutes les étapes Splitter (General Splitter / Iterating Splitter) doivent activer le streaming (<ifl:property key="streaming" value="true"/>) et utiliser des expressions XPath directes sans prédicats lourds.
  • Ne passez jamais de mégas-payloads (> 50 Mo) directement dans un Message Mapping graphique (piège DOM) ; placez toujours un Splitter en streaming avant le Message Mapping.
• Optimisation du Routeur :
  • Extrayez les valeurs XML dans des propriétés d'échange typées (java.lang.String, java.lang.Long) dans un Content Modifier avant le Router, et évaluez ${property.Field} (Camel Simple) au lieu d'évaluer des XPath répétés sur plusieurs branches du routeur.
  • Ordonnez les branches du routeur de la plus fréquente à la moins fréquente, et définissez toujours une route default sur <bpmn2:exclusiveGateway>.
• Tous les points de terminaison externes doivent utiliser https:// et des paramètres externalisés {{PARAM_NAME}}.
• Toutes les tâches ExternalCall synchrones doivent déclarer une propriété timeout explicite (ex., 60000).
• Chaque tâche de script doit référencer <ifl:property key="scriptFunction" value="processData"/> et <ifl:property key="script" value="<fileName>"/>.
• Doit inclure les coordonnées <bpmndi:BPMNDiagram> pour que l'éditeur d'interface utilisateur Web de SAP CPI rende le diagramme proprement.
• Patrons Optionnels pour des Gestionnaires Transversaux Réutilisables :
  • Gestionnaire Centralisé d'Erreurs et d'Observabilité (ProcessDirect -> Parallel Multicast) :
    • Reçoit une enveloppe XML d'erreur via ProcessDirect ({{PD_address}}) depuis les Exception Subprocess d'autres iFlows, soutenu par un XSD tolérant où tous les champs sont minOccurs="0" nillable="true" (incluant Environment, InterfaceName, InterfaceDescription, ObjectID, ExceptionMessage, OriginalMessageProcessingLogID, SAP_MessageProcessingLogID, SAP_MplCorrelationId et des indicateurs comme SendBody).
    • Utilise un Parallel Multicast pour diviser le flux en deux branches : (1) une branche d'alerte par e-mail (Mail SMTP avec starttls_mandatory) qui formate un tableau HTML dans un Content Modifier, et (2) une branche d'observabilité vers SAP Cloud Logging / OpenSearch qui évalue ${property.SendBody.toLowerCase()} = 'yes' dans un Router pour choisir entre deux Message Mapping (WithBody.mmap vs NoBody.mmap), convertit la sortie avec XML to JSON Converter (xmlJsonSuppressRootElement=true) et l'envoie par HTTP POST avec certificat client ({{CloudLoggingCertificate}}).
    • Inclut son propre Exception Subprocess local qui inspecte CamelExceptionCaught et enregistre le détail comme pièce jointe MPL (addAttachmentAsString) pour éviter les boucles infinies si le serveur de messagerie ou de logs échoue.
  • Gestionnaire Centralisé de Rafraîchissement de Jeton (StartTimerEvent -> LocalIntegrationProcess -> Global Data Store) :
    • Démarre avec un StartTimerEvent paramétré ({{TokenTimer}} de type custom:schedule dans parameters.propdef), délègue l'appel ExternalCall et l'extraction du jeton à un LocalIntegrationProcess (processType="directCall"), nettoie les en-têtes et les propriétés internes dans un Content Modifier via des actions Delete ($name=Authorization, $name=SAP_MonitoringStateProperties, $name=Content-Length, etc.) et persiste l'en-tête/le jeton dans un Data Store Global Chiffré (activityType="DBstorage", operation="put", visibility="global", encrypt="true", override="true", includeMessageHeaders="true").

Étape 3 : Scripts Groovy (src/main/resources/script/*.groovy)

Rédigez chaque script Groovy planifié dans groovyScriptsPlan[] en suivant toutes les Directives de Script SAP CPI (def Message processData(Message message), streaming Reader, JsonSlurperClassic, XmlSlurper avec disallow-doctype-decl, ZoneId.of("UTC"), pièces jointes MPL conditionnelles, relance d'exception CPI-ERR:).

Étape 4 : Validation et Construction des Bundles OSGi (.zip)

Sauvegardez votre spécification JSON (contenant iflowName, scriptCollectionName, businessDescription, parameters, iflwXml et groovyScripts) et exécutez build-cpi-package.mjs :

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

• Script de packaging et validation OSGi : build-cpi-package.mjs
• Spécification du bundle OSGi : osgi-bundle-spec.md
• Porte de Vérification et Conformité du Manifeste OSGi :
  • build-cpi-package.mjs valide à la fois le XML BPMN2 .iflw et chaque script Groovy avant de produire <iflowName>.zip, <scriptCollectionName>.zip et Paquete_<iflowName>.zip.
  • Place .project et META-INF/MANIFEST.MF directement à la racine du .zip (jamais imbriqué dans un dossier wrapper de niveau supérieur) et enveloppe toutes les lignes de MANIFEST.MF à 72 octets UTF-8 avec des continuations \r\n pour que SAP CPI n'échoue jamais avec "The project must contain a valid manifest file".
  • Rappelez toujours à l'utilisateur de télécharger <scriptCollectionName>.zip (dans Add -> Script Collection) et <iflowName>.zip (dans Add -> Integration Flow) individuellement, plutôt que de télécharger le wrapper externe Paquete_<iflowName>.zip.

---

Mode 2 : Documenter un iFlow Existant (Rétro-Ingénierie en 8 Sections)

Étape 0 : Clarification du Périmètre Documentaire

Avant de rédiger la documentation technique, vérifiez :

1. Si l'utilisateur a fourni le chemin d'accès au fichier .zip ou .iflw. S'il ne l'a pas indiqué, demandez-lui le chemin du package.
2. S'il est nécessaire d'accentuer un aspect spécifique pour le public visé par le document (ex. équipe Opérations/Support, audit de sécurité BTP, ou transfert vers la Production) ou d'ajouter un contexte métier qui ne figure pas dans le .iflw.

Étape 1 : Extraire le Contexte et les Heuristiques du .zip

Exécutez extract-for-docs.mjs sur le bundle .zip existant :

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

• Script extracteur et validateur de documentation : extract-for-docs.mjs
• Modèle en 8 sections : doc-template-8-sections.md

Étape 2 : Rédiger et Valider les 8 Sections Obligatoires

Rédigez la documentation Markdown en suivant exactement les 8 titres de doc-template-8-sections.md et validez le fichier .md généré avec :

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

---

Mode 3 : Cloner et Adapter des Bundles de Référence (.zip) selon une Nouvelle Spécification

Utilisez ce mode lorsque l'utilisateur fournit un package SAP CPI existant (.zip contenant un ou plusieurs iFlows et/ou une ScriptCollection) et demande à créer de nouvelles intégrations ou à mettre à jour des intégrations existantes en fonction d'un document de spécification d'API (PDF, Markdown, OpenAPI).

Étape 0 : Analyse des Écarts (Gap Analysis) et Règle de Confidentialité

1. Inspection sans Exposition de Données Privées (Privacy-First) :
   • Inspectez la structure des .zip avec inspect-iflow-zip.mjs (qui masque automatiquement les valeurs de .prop comme [REDACTED]).
   • NE JAMAIS lire ni imprimer les valeurs sensibles de parameters.prop (identifiants, points de terminaison privés, files d'attente internes) ni télécharger des packages client dans le dépôt Git, sauf instruction explicite.
2. Contraste Spécification vs. Implémentation et Questions de Clarification :
   • Comparez les filtres de requête, les champs demandés, les tables de résolution de références et les schémas JSON/XML entre le bundle de référence et le document de spécification.
   • Si le document présente des points ouverts, des champs hérités d'entités parentes (dot-walking vs null), ou des divergences de noms de champs (ex. champ canonique vs champ alternatif), demandez à l'utilisateur avant d'écrire du code en proposant d'abord l'option recommandée.

Étape 1 : Adapter ou Créer les Scripts dans la Script Collection

1. Créez les nouveaux scripts .groovy (et mettez à jour les existants si l'utilisateur l'a demandé) en conservant le modèle architectural de la Script Collection d'origine.
2. Assurez-vous que :
   • Dans les scripts Groovy 2.4 (com.sap.gateway.ip.core.customdev.util.Message), il faut importer groovy.util.XmlSlurper (jamais groovy.xml.XmlSlurper, qui échoue à la compilation avec "unable to resolve class groovy.xml.XmlSlurper").
   • Lors de la lecture depuis un Reader (BufferedReader / StringReader), ne jamais invoquer bodyReader.getText('UTF-8') avec un paramètre de jeu de caractères (lève MissingMethodException) ; utilisez bodyReader.getText() sans arguments ou passez bodyReader directement à .parse(bodyReader).
   • Toute constante au niveau du script avec @Field inclue final (@Field final), l'analyse XML désactive disallow-doctype-decl, et l'analyse JSON utilise JsonSlurperClassic.
3. Validez tous les scripts en lot avec validate-groovy.mjs :

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

Étape 2 : Cloner les iFlows et Empaqueter la Script Collection

Exécutez clone-iflow-bundle.mjs pour cloner chaque iFlow de référence (en mettant à jour .project, META-INF/MANIFEST.MF, metainfo.prop, <NuevoNombre>.iflw, les références aux scripts .groovy et les expressions XPath du Splitter) et pour injecter les nouveaux scripts dans la Script Collection .zip :

# 1. Cloner et adapter un iFlow .zip en conservant intacts ses diagrammes BPMN2 et .prop
node ./scripts/clone-iflow-bundle.mjs --source <Referencia_iFlow.zip> --target-name <Nuevo_iFlow> --out <Nuevo_iFlow.zip> --replace <ScriptViejo.groovy=ScriptNuevo.groovy> --xpath <//nodoViejo=//nodoNuevo> [--add-resource <Esquema.xsd>] [--add-resource <Mapeo.mmap>]

# 2. Injecter ou mettre à jour des fichiers individuels (.xsd, .mmap, .xsl, .wsdl, .groovy) dans un iFlow .zip existant (sans le renommer)
node ./scripts/clone-iflow-bundle.mjs --source <iFlow_Existente.zip> --add-resource <NuevoEsquema.xsd> --add-resource <NuevoMapeo.mmap> --out <iFlow_Actualizado.zip>

# 3. Mettre à jour la Script Collection .zip avec les nouveaux scripts validés
node ./scripts/clone-iflow-bundle.mjs --update-sc <SC_Origen.zip> --scripts-dir <carpeta-scripts> --out <SC_Actualizada.zip> --strict

• Script de clonage et de mise à jour de la SC : clone-iflow-bundle.mjs
• Script d'inspection du bundle : inspect-iflow-zip.mjs

Étape 3 : Ajustements Finaux et Validation

1. Si le package .zip de la Script Collection est le seul artefact livré, définissez <iflowName> comme null dans generate-full-spec.mjs et appelez-le directement.
2. Validez le bundle final avec build-cpi-package.mjs en mode vérification uniquement :

node ./scripts/build-cpi-package.mjs --verify <Nuevo_iFlow.zip> <SC_Actualizada.zip>

---

Dépendances et Outils

Script	Usage	Référence de spécification
build-cpi-package.mjs	Générer les bundles .zip OSGi à partir de la spécification JSON	osgi-bundle-spec.md
extract-for-docs.mjs	Extraire les métadonnées d'un .zip existant / Valider le document .md	doc-template-8-sections.md
clone-iflow-bundle.mjs	Cloner, renommer et adapter les bundles .zip / Mettre à jour les Script Collections	(Intégré)
inspect-iflow-zip.mjs	Inspecter la structure du .zip et les .prop (valeurs masquées)	(Intégré)
validate-groovy.mjs	Valider la syntaxe Groovy et les règles CPI (censure XmlSlurper, getText())	(Intégré)

---

Consignes Générales (Application à Tous les Modes)

1. Respecter les Directives de Conception SAP : Tous les iFlows générés doivent suivre les SAP Integration Flow Design Guidelines, en utilisant Content Modifier avant le Router, des Splitter en streaming, des ExternalCall avec timeout, et des Exception Subprocess avec gestion des transactions.
2. Externaliser Tous les Paramètres : Aucune URL, identifiant, file d'attente, délai d'attente ou jeton ne doit être en dur dans le XML .iflw ou les scripts .groovy – tous doivent être définis comme {{PARAM_NAME}} avec des valeurs par défaut dans le plan parameters.
3. Rester dans la Sandbox de Spécification : Ne tentez pas d'exécuter build-cpi-package.mjs (ni aucun autre script d'outillage) sans que l'utilisateur ne l'autorise explicitement. Déposez toute la spécification, le XML et les scripts dans la conversation et attendez les instructions.
4. Assertions de Conformité du Manifeste : Ne produisez jamais un .zip avec .project ou META-INF/MANIFEST.MF à l'intérieur d'un dossier wrapper. La racine du .zip doit être directement le dossier du projet iFlow, et chaque ligne de MANIFEST.MF doit être enveloppée à 72 octets avec \r\n .
5. Règles d'Import Groovy :
   • Utilisez import groovy.util.XmlSlurper (jamais groovy.xml.XmlSlurper).
   • Utilisez import groovy.json.JsonSlurperClassic.
   • Utilisez import java.time.ZoneId.
6. Limites de Taille des Fichiers : Aucun fichier individuel dans le bundle .zip ne doit dépasser 10 Mo. Les payloads volumineux doivent être divisés en utilisant un Splitter.

---

Proposition de Flux de Travail pour l'Utilisateur

1. Décrire l'intégration en langage naturel (ex., "Je veux synchroniser les commandes de Salesforce vers S/4HANA toutes les 30 minutes").
2. (Mode 1) L'IA clarifie les détails manquants, génère un plan architectural, suit avec le XML .iflw, puis les scripts Groovy, et propose de packager.
3. L'utilisateur approuve la spécification et exécute build-cpi-package.mjs.
4. Télécharger la Script Collection et le package iFlow dans SAP Integration Suite.
5. (Mode 2) Pour un iFlow existant, exécutez extract-for-docs.mjs et examinez la documentation en 8 sections.
6. (Mode 3) Pour un bundle de référence, exécutez inspect-iflow-zip.mjs, lisez la spécification cible, confirmez les adaptations, puis exécutez clone-iflow-bundle.mjs.