SAP RFC / BAPI

El camino síncrono: el CMS llama a SAP. Una Recolección llama una función y convierte el retorno en mensaje; una Entrega convierte el mensaje en parámetros de una llamada. Ver SAP para la visión general de los tres caminos.

Arquitectura

La integración RFC no corre dentro de cms-api. Vive en el microservicio cms-sap-connector, que aísla el SAP NetWeaver RFC SDK (código nativo en C, vía node-rfc) del proceso principal.

Motivo: un crash de addon nativo derribaría la API, el programador y los workers junto. En un proceso separado, derriba únicamente la integración SAP.

El servicio queda solo en la red interna del docker-compose (cms-network), sin puerto publicado y sin pasar por nginx. Los endpoints excepto /health exigen el header X-Internal-Token cuando SAP_CONNECTOR_TOKEN está configurada.

Instalar el SDK

La comunicación usa el SAP NetWeaver RFC SDK oficial, la misma biblioteca de integraciones RFC en producción. No hay emulación ni traducción intermedia: la llamada sale del connector directo al gateway RFC de su SAP, con el mismo protocolo de un programa ABAP remoto.

El SDK está licenciado por SAP y no puede redistribuirse, por eso no viene embebido en la imagen.

Configurar la conexión

En la Conexión Externa de tipo SAP, el bloque de RFC client acepta dos modos de conexión:

Además: mandante, usuario, contraseña, idioma, SAProuter (opcional), tamaño del pool de conexiones y la función usada en la prueba (por defecto RFC_PING).

El campo Timeout (ms), junto a la función de prueba, es el plazo de Probar Conexión y del Keep Alive: vacío vale 10000, y acepta de 1000 a 60000. Sirve para el SAP que responde despacio — por SAProuter, VPN o desde otro continente — y que, con el plazo fijo de antes, quedaba OFF aun estando en línea. En las consultas de metadatos (describir la función o la estructura, buscar la BAPI) el campo solo aumenta el plazo predeterminado de ellas, nunca lo reduce. Las llamadas de Recolección y Entrega no usan este campo: cada una tiene su timeout propio.

El botón Probar Conexión hace una llamada real y devuelve el error de SAP cuando falla — es donde aparecen los clásicos de implantación: usuario bloqueado, mandante equivocado, SAProuter inaccesible.

Recolección — SAP_RFC

Llama un módulo de función o BAPI y convierte el retorno en mensaje.

Encontrar la función

El botón de búsqueda busca funciones en SAP por nombre o fragmento, y muestra la descripción de cada una. Al elegir, el CMS importa la firma: parámetros de IMPORT, de EXPORT y las tablas.

Declarar los parámetros

Los parámetros se declaran en JSON, pero se editan haciendo clic en los campos del popup Parámetros Función SAP. Cada parámetro de IMPORT tiene un origen:

Estructuras. Un parámetro de estructura se abre en un editor propio (Monaco, en JSON), con el panel de variables al lado: las Variables de Entrada de la Recolección/Entrega y las Globales. Se puede crear una Variable de Entrada nueva directamente desde el panel y usarla enseguida en la estructura — {"SHORT_TEXT": "{{descricao}}", "EQUIPMENT": "{{equipamento}}"}.

Variables de Entrada libres. Además de las que nacen de un parámetro “viene de afuera”, usted puede declarar variables que solo aparecen dentro de estructuras o de llamadas siguientes. Entran en el contrato de la misma forma.

En Parámetros TABLES, out lista las tablas de salida a devolver, e in (opcional) mapea las tablas de entrada — origen fixo (array literal de filas) o jsonpath.

{
  "in":  { "PLANTSELECTION": { "origem": "fixo",
           "valor": "[{\"SIGN\":\"I\",\"OPTION\":\"EQ\",\"PLANT_LOW\":\"1000\"}]" } },
  "out": ["RETURN", "T_MATERIAIS"]
}

Recolección programada o bajo demanda

Aquí hay una decisión de proyecto que cambia el comportamiento de toda la integración:

• sin Variables de Entrada — la Recolección la recorre el programador, en el cron configurado;
• con al menos una Variable de Entrada — la Recolección sale del programador y gana una URL propia, ejecutada bajo demanda por quien la llame.

En modo bajo demanda, si falta una variable obligatoria, la API rechaza con HTTP 400 en el acto — no se convierte en mensaje con error. Ver API pública.

Probar sin salir del CMS

El botón de prueba ejecuta la función con los parámetros declarados y muestra el retorno. Es lo que evita el ciclo “guarda, espera el cron, mira el mensaje con error, corrige”.

Para tablas grandes, existe además el popup de campos de la tabla, que lista las columnas del retorno y permite espiar valores — útil para descubrir el nombre exacto del campo antes de escribir el Transformador.

Caché de metadatos

Los metadatos de la función (parámetros de import/export y tablas) quedan guardados en caché local en la base de datos. El popup de parámetros funciona offline, y un botón “Actualizar desde SAP” recarga cuando la función cambia en el ERP.

Entrega — SAP_RFC_CALL

El camino inverso: los datos del mensaje se vuelven parámetros de una llamada RFC/BAPI.

La configuración es la misma — función, parámetros IMPORT, parámetros TABLES — con dos diferencias importantes.

Payload de Entrada

Los campos marcados “viene de afuera” forman el Payload de Entrada: el contrato que el mensaje entregado debe cumplir. Cada alias resuelve contra el payload del mensaje, y marcar uno como obligatorio hace que el CMS rechace el envío, con un mensaje claro, cuando el campo no viene.

Commit

Las BAPIs de escritura no graban nada hasta el commit. La opción “Llamar BAPI_TRANSACTION_COMMIT después de la llamada” hace que el connector lo emita en la misma sesión RFC de la llamada — y de las llamadas siguientes, después de la última. Si el RETURN de algún paso viene con tipo E o A, el connector hace BAPI_TRANSACTION_ROLLBACK en lugar del commit.

Llamar a continuación, en la misma sesión

Algunas BAPIs solo funcionan en pareja: BAPI_ALM_NOTIF_CREATE arma el aviso de PM en la memoria de la sesión, y solo BAPI_ALM_NOTIF_SAVE lo graba — en la misma sesión. Cada mensaje del CMS abre su propia conexión RFC, así que dos Entregas encadenadas (o una respuesta reenviada) no sirven: el aviso creado en la primera no existe en la segunda.

La sección “Llamar a continuación, en la misma sesión” agrega pasos a la misma Entrega (y a la Recolección), ejecutados uno después del otro en la conexión de la función principal:

• cada paso tiene su función (con la misma búsqueda en SAP), sus parámetros de import y las tablas de salida;
• el origen resposta (Respuesta anterior) lee un campo del paso anterior — NOTIFHEADER_EXPORT.NOTIF_NO, por ejemplo. La pantalla lista los campos de salida del paso anterior y sugiere el del mismo nombre;
• los campos del payload de entrada y las estructuras funcionan como en la función principal;
• el retorno de cada paso entra en el resultado con el nombre de la función (BAPI_ALM_NOTIF_SAVE.NOTIFHEADER.NOTIF_NO).

El editor del paso se completa a partir de SAP: al elegir la función, los parámetros de import aparecen listos para mapear, y las tablas de salida se eligen en un popup.

Errores

El error de SAP llega al CMS con el texto original, en el idioma de la conexión. A partir de ahí:

• una falla de comunicación (gateway caído, usuario bloqueado) se vuelve Error de Entrega, con reintentos;
• un retorno de negocio (la tabla RETURN con tipo E) se vuelve Error de Negocio cuando hay una regla registrada — y así es como “orden no liberada” deja de parecer un éxito.

Los Packs SAP ya traen esas reglas listas para los escenarios que cubren.