nololsabias-spec/sap-cpi-architect

SAP CPI Architect: Generador, Clonador y Documentador de Ingeniería Inversa de iFlows

Opera en tres modos especializados:

• Modo 1 · Generar iFlow + Script Collection (.zip): Diseña un iFlow de grado empresarial en 3 etapas (Plan -> BPMN2 .iflw XML -> Scripts Groovy), valida todos los artefactos y construye bundles OSGi .zip reales importables en SAP Integration Suite.
• Modo 2 · Documentar iFlow Existente: Extrae un bundle .zip existente, ejecuta heurísticas estáticas y genera la documentación técnica y arquitectónica de 8 secciones.
• Modo 3 · Clonar y Adaptar Bundles de Referencia (.zip) según Nueva Especificación: Clona una plantilla .zip de iFlow + Script Collection existente, adapta scripts, splitters XPath y descriptores OSGi a una nueva especificación funcional/de API, y preserva los archivos .prop privados intactos.

---

Modo 1: Generar iFlow + Script Collection (Pipeline en 3 Etapas)

Etapa 0: Protocolo de Clarificación Interactiva (Preguntar antes de Asumir)

Antes de generar el plan arquitectónico o el paquete .zip, analiza si el prompt del usuario define todos los parámetros críticos del flujo de integración. Si falta información clave, realiza preguntas breves y estructuradas (proponiendo valores recomendados) para obtener el contexto necesario:

1. Sistemas Origen y Destino (Sender / Receiver): ¿Qué adaptadores utilizan (HTTPS, OData v2/v4, SFTP, SOAP, IDoc, JMS, ProcessDirect) y si la comunicación es síncrona (Request-Reply) o asíncrona?
2. Contratos de Datos y Transformaciones: ¿Qué formato entra y sale (JSON, XML, IDoc, CSV) y qué reglas de negocio o enriquecimientos (Content Modifier, Router, Groovy Script) deben aplicarse?
3. Seguridad y Parámetros Externalizados: ¿Qué método de autenticación requiere cada endpoint (OAuth2 Client Credentials, Basic Auth / User Credential alias, Client Certificate) y qué timeouts se esperan?
4. Gestión de Errores y Alertas: ¿Qué debe hacer el Exception Subprocess cuando ocurre un fallo (enviar alerta por correo, guardar en cola JMS, retornar estructura de error HTTP personalizada)?

Regla de Vía Rápida: Si el usuario ya proporcionó una especificación completa o pide explícitamente que asumas valores por defecto de mejores prácticas SAP, procede directamente a la Etapa 1 documentando los supuestos tomados.

Etapa 1: Plan Arquitectónico (plan.json)

Diseña el plan JSON que contiene:

• iflowName (PascalCase con guiones bajos, ej., Order_Sync_S4HANA)
• scriptCollectionName (SC_<iflowName>)
• businessDescription y technicalSummary
• parameters (cada URL externa, alias de credencial o timeout externalizado como KEY: defaultValue)
• components[] (pasos ordenados: StartEvent, ContentModifier, RequestReply, Router, ScriptTask, ExceptionSubprocess, EndEvent)
• groovyScriptsPlan[] ({ fileName, purpose })

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

Genera el XML BPMN 2.0 completo implementando cada paso del plan siguiendo las Directrices Oficiales de Diseño de Flujos de Integración de SAP:

• Debe incluir <bpmn2:definitions> con los namespaces bpmn2, bpmndi, ifl, dc, di.
• Debe incluir <bpmn2:collaboration> (Sender, Receiver, Integration Process) y <bpmn2:process>.
• Debe incluir <bpmn2:subProcess triggeredByEvent="true" ifl:type="ExceptionSubProcess"> (o ErrorEventSubProcessTemplate):
  • Arquitectura Resiliente de Errores y Transacciones: Diferencia entre errores transitorios (usa colas JMS con reintento/backoff automático) y errores persistentes/poison (enruta a un Data Store o Dead-Letter Queue en el Exception Subprocess, y opcionalmente envía alertas vía ProcessDirect a un iFlow central de registro de errores). Mantén los límites de transacción cortos aislando los pasos transaccionales dentro de Procesos de Integración Locales.
• Regla "Split-First" para Splitter y Message Mapping Streaming:
  • Todos los pasos Splitter (General Splitter / Iterating Splitter) deben habilitar streaming (<ifl:property key="streaming" value="true"/>) y usar expresiones XPath directas sin predicados pesados.
  • Nunca pases mega-payloads (> 50 MB) directamente a un Message Mapping gráfico (trampa DOM); siempre coloca un Splitter con streaming antes del Message Mapping.
• Optimización de Router:
  • Extrae valores XML en propiedades de Exchange tipadas (java.lang.String, java.lang.Long) en un Content Modifier antes del Router, y evalúa ${property.Field} (Camel Simple) en lugar de evaluar XPath repetido a través de múltiples ramas del Router.
  • Ordena las ramas del Router de la más frecuente a la menos frecuente, y define siempre una ruta default en <bpmn2:exclusiveGateway>.
• Todos los endpoints externos deben usar https:// y parámetros externalizados {{PARAM_NAME}}.
• Todas las tareas ExternalCall síncronas deben declarar una propiedad timeout explícita (ej., 60000).
• Cada Script Task debe referenciar <ifl:property key="scriptFunction" value="processData"/> y <ifl:property key="script" value="<fileName>"/>.
• Debe incluir coordenadas <bpmndi:BPMNDiagram> para que el editor de la interfaz web de SAP CPI renderice el diagrama de forma limpia.
• Patrones Opcionales para Handlers Transversales Reutilizables:
  • Handler Centralizado de Errores y Observabilidad (ProcessDirect -> Parallel Multicast ):
    • Recibe un sobre XML de error vía ProcessDirect ({{PD_address}}) desde los Exception Subprocess de otros iFlows, respaldado por un XSD tolerante donde todos los campos son minOccurs="0" nillable="true" (incluyendo Environment, InterfaceName, InterfaceDescription, ObjectID, ExceptionMessage, OriginalMessageProcessingLogID, SAP_MessageProcessingLogID, SAP_MplCorrelationId y banderas como SendBody).
    • Usa un Parallel Multicast para dividir el flujo en dos ramas: (1) una rama de alerta por correo (Mail SMTP con starttls_mandatory) que formatea una tabla HTML en un Content Modifier, y (2) una rama de observabilidad hacia SAP Cloud Logging / OpenSearch que evalúa ${property.SendBody.toLowerCase()} = 'yes' en un Router para elegir entre dos Message Mapping (WithBody.mmap vs NoBody.mmap), convierte la salida con XML to JSON Converter (xmlJsonSuppressRootElement=true) y la envía por HTTP POST con certificado de cliente ({{CloudLoggingCertificate}}).
    • Incluye su propio Exception Subprocess local que inspecciona CamelExceptionCaught y guarda el detalle como adjunto MPL (addAttachmentAsString) para evitar bucles infinitos si falla el servidor de correo o de logs.
  • Handler Centralizado de Refresco de Tokens (StartTimerEvent -> LocalIntegrationProcess -> Global Data Store ):
    • Inicia con un StartTimerEvent parametrizado ({{TokenTimer}} de tipo custom:schedule en parameters.propdef), delega la llamada ExternalCall y extracción del token a un LocalIntegrationProcess (processType="directCall"), limpia cabeceras y propiedades internas en un Content Modifier mediante acciones Delete ($name=Authorization, $name=SAP_MonitoringStateProperties, $name=Content-Length, etc.) y persiste la cabecera/token en un Data Store Global Cifrado (activityType="DBstorage", operation="put", visibility="global", encrypt="true", override="true", includeMessageHeaders="true").

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

Redacta cada script Groovy planificado en groovyScriptsPlan[] siguiendo todas las Directrices de Scripting de SAP CPI (def Message processData(Message message), streaming Reader, JsonSlurperClassic, XmlSlurper con disallow-doctype-decl, ZoneId.of("UTC"), adjuntos MPL condicionales, relanzamiento de excepción CPI-ERR:).

Etapa 4: Validación y Construcción de los Bundles OSGi (.zip)

Guarda tu JSON de especificación (que contiene iflowName, scriptCollectionName, businessDescription, parameters, iflwXml y groovyScripts) y ejecuta build-cpi-package.mjs:

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

• Script empaquetador y validador OSGi: build-cpi-package.mjs
• Especificación del Bundle OSGi: osgi-bundle-spec.md
• Gate de Verificación y Cumplimiento del Manifiesto OSGi:
  • build-cpi-package.mjs valida tanto el XML .iflw BPMN2 como cada script Groovy antes de producir <iflowName>.zip, <scriptCollectionName>.zip y Paquete_<iflowName>.zip.
  • Coloca .project y META-INF/MANIFEST.MF directamente en la raíz del .zip (nunca anidados dentro de una carpeta contenedora de nivel superior) y ajusta todas las líneas de MANIFEST.MF a 72 bytes UTF-8 con contiuaciones \r\n para que SAP CPI nunca falle con "El proyecto debe contener un archivo de manifiesto válido".
  • Siempre recuerda al usuario que cargue <scriptCollectionName>.zip (en Add -> Script Collection) y <iflowName>.zip (en Add -> Integration Flow) individualmente, en lugar de cargar el contenedor externo Paquete_<iflowName>.zip.

---

Modo 2: Documentar iFlow Existente (Ingeniería Inversa en 8 Secciones)

Paso 0: Clarificación de Alcance Documental

Antes de redactar la documentación técnica, verifica:

1. Si el usuario ha proporcionado la ruta al archivo .zip o .iflw. Si no lo ha indicado, pídele la ruta del paquete.
2. Si necesita enfatizar algún aspecto específico para la audiencia del documento (ej., equipo de Operaciones/Soporte, auditoría de Seguridad BTP, o traspaso a Producción) o añadir contexto de negocio que no figure dentro del .iflw.

Paso 1: Extraer Contexto y Heurísticas del .zip

Ejecuta extract-for-docs.mjs sobre el bundle .zip existente:

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

• Script extractor y validador de documentos: extract-for-docs.mjs
• Plantilla de 8 Secciones: doc-template-8-sections.md

Paso 2: Redactar y Validar las 8 Secciones Obligatorias

Escribe la documentación en Markdown siguiendo exactamente los 8 encabezados de doc-template-8-sections.md y valida el archivo .md generado con:

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

---

Modo 3: Clonar y Adaptar Bundles de Referencia (.zip) según Nueva Especificación

Usa este modo cuando el usuario proporciona un paquete SAP CPI existente (.zip que contiene uno o más iFlows y/o una ScriptCollection) y solicita crear nuevas integraciones o actualizar las existentes basándose en un documento de especificación de API (PDF, Markdown, OpenAPI).

Paso 0: Análisis de Brechas (Gap Analysis) y Regla de Privacidad

1. Inspección sin Exposición de Datos Privados (Privacy-First):
   • Inspecciona la estructura de los .zip con inspect-iflow-zip.mjs (que redacta automáticamente los valores de .prop como [REDACTED]).
   • NUNCA leas ni imprimas valores sensibles de parameters.prop (credenciales, endpoints privados, colas internas) ni subas paquetes de cliente al repositorio Git salvo instrucción explícita.
2. Contraste Especificación vs. Implementación y Preguntas de Clarificación:
   • Compara los filtros de consulta, campos solicitados, tablas de resolución de referencias y esquemas JSON/XML entre el bundle de referencia y el documento de especificación.
   • Si el documento presenta puntos abiertos, campos heredados de entidades padre (dot-walking vs null), o discrepancias de nombres de campo (ej., campo canónico vs campo alternativo), pregunta al usuario antes de escribir código proponiendo la opción recomendada primero.

Paso 1: Adaptar o Crear los Scripts en la Script Collection

1. Crea los nuevos scripts .groovy (y actualiza los existentes si el usuario lo solicitó) manteniendo el patrón arquitectónico de la Script Collection original.
2. Asegúrate de que:
   • En scripts Groovy 2.4 (com.sap.gateway.ip.core.customdev.util.Message), se importe groovy.util.XmlSlurper (nunca groovy.xml.XmlSlurper, que falla al compilar con "unable to resolve class groovy.xml.XmlSlurper").
   • Al leer desde un Reader (BufferedReader / StringReader), nunca se invoque bodyReader.getText('UTF-8') con parámetro de charset (lanza MissingMethodException); usa bodyReader.getText() sin argumentos o pasa bodyReader directamente a .parse(bodyReader).
   • Toda constante a nivel de script con @Field incluya final (@Field final), el parseo XML deshabilite disallow-doctype-decl, y el parseo JSON use JsonSlurperClassic.
3. Valida todos los scripts en lote con validate-groovy.mjs:

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

Paso 2: Clonar los iFlows y Empaquetar la Script Collection

Ejecuta clone-iflow-bundle.mjs para clonar cada iFlow de referencia (actualizando .project, META-INF/MANIFEST.MF, metainfo.prop, <NuevoNombre>.iflw, referencias a scripts .groovy y expresiones XPath del Splitter) y para inyectar los nuevos scripts en la Script Collection .zip:

# 1. Clonar y adaptar un iFlow .zip manteniendo intactos sus diagramas BPMN2 y .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. Inyectar o actualizar archivos sueltos (.xsd, .mmap, .xsl, .wsdl, .groovy) en un iFlow .zip existente (sin renombrarlo)
node ./scripts/clone-iflow-bundle.mjs --source <iFlow_Existente.zip> --add-resource <NuevoEsquema.xsd> --add-resource <NuevoMapeo.mmap> --out <iFlow_Actualizado.zip>

# 3. Actualizar la Script Collection .zip con los nuevos scripts validados
node ./scripts/clone-iflow-bundle.mjs --update-sc <SC_Origen.zip> --scripts-dir <carpeta-scripts> --out <SC_Actualizada.zip> --strict

• Script de clonación y actualización de SC: clone-iflow-bundle.mjs
• Script de inspección de .zip (redacta .prop): inspect-iflow-zip.mjs

---

Referencias

• Especificación del Bundle OSGi
• Plantilla de Documentación de 8 Secciones
• Guía de Mejores Prácticas de Scripting Groovy en CPI