Solución de problemas de Design Studio

Esta guía cubre errores y problemas comunes al usar Jitterbit Design Studio. Comienza con los pasos de diagnóstico a continuación, luego encuentra tu problema específico en la sección correspondiente.

Para una referencia unificada que cubra problemas de integración, automatización, gestión de API, EDI y desarrollo de aplicaciones en un solo lugar, consulta la guía de solución de problemas de Harmony.

Si un agente privado ejecuta tus operaciones de Design Studio, consulta la solución de problemas del agente privado para problemas con el agente mismo. Para errores que ocurren cuando se ejecutan operaciones, la guía de solución de problemas de operaciones cubre Studio en lugar de Design Studio, pero muchas de las entradas (por ejemplo, operaciones atascadas, errores de script y fallos de conexión) también son aplicables a operaciones de Design Studio.

• Conector SAP

  -   [IDocs no encontrados cuando una operación programada se ejecuta en un agente diferente](#sap-idc-multi-agent)
  -   [Los envíos masivos de IDoc pueden exceder los límites de conexión del endpoint de destino](#sap-idc-bulk)
  -   [Carga útil de SAP IDoc perdida cuando el endpoint de destino no es accesible](#sap-idoc-payload-lost)
  -   [Almacenamiento y reenvío de SAP IDoc: Archivos temporales eliminados después de 24 horas](#sap-idoc-temp-files)
  -   [La operación BAPI se realiza correctamente pero la transacción no se confirma en SAP](#bapi-no-commit)
  -   [El Listener de eventos de SAP no detecta IDocs en Windows](#sap-event-listener-no-trigger)
  

Pasos de diagnóstico

Revisar el registro de errores

Design Studio muestra los errores del sistema en un panel de errores integrado. Selecciona Error Log en el menú View para abrirlo. Cada error aparece como una entrada separada con una descripción. Para guardar los detalles del error en un caso de soporte, haz clic en Save en la esquina superior derecha del panel de errores.

Revisar la página de problemas conocidos

Consulta la página Problemas conocidos de Design Studio para ver los problemas identificados en versiones recientes de Design Studio.

Errores de inicio de sesión y conexión

Error de certificado SSL o configuración de filtro proxy

• Síntoma: Design Studio muestra un error de certificado SSL o filtro proxy al intentar iniciar sesión.
• Posibles causas:
  • Un certificado SSL o CA firmado utilizado por tu red (por ejemplo, de un filtro web, proxy o VPN) no está presente en el almacén de claves Java de Jitterbit.
  • La lista de permitidos de IP para tu proxy de red o filtro web no incluye las direcciones de Jitterbit requeridas. Consulta Información de lista de permitidos.
• Resolución: Para obtener los pasos de resolución completos, incluida la forma de agregar certificados al almacén de claves Java de Jitterbit, consulta Error de certificado SSL o configuración de filtro proxy.

Los usuarios de SSO fuera de la región de la organización no pueden iniciar sesión

• Síntoma: Después de que se habilita el inicio de sesión único (SSO) de Harmony para la organización, los usuarios cuya región de Harmony es diferente de la región predeterminada a la que se conecta el diálogo de inicio de sesión de Design Studio no pueden completar el inicio de sesión de SSO. Los usuarios en la región predeterminada inician sesión sin problemas.
• Posible causa: Design Studio se conecta de forma predeterminada a una única URL de región de Harmony en el diálogo de inicio de sesión. Cuando se habilita SSO, la redirección de SSO se resuelve solo en la región de Harmony que aloja la organización, por lo que los usuarios deben apuntar Design Studio a la URL de esa región antes de iniciar sesión.
• Resolución:
  • En el diálogo de inicio de sesión de Design Studio, presiona Ctrl + Shift + U para abrir el campo de URL. Ingresa la URL para la región de Harmony de la organización (por ejemplo, https://na-east.jitterbit.com para NA o https://emea-west.jitterbit.com para EMEA), luego completa el inicio de sesión de SSO.
  • Para hacer que el cambio sea persistente, establece la URL en el archivo de configuración client.properties:
    • Abre <Jitterbit Studio Home>\configuration\client.properties en un editor de texto (en macOS, la ruta es /Applications/Jitterbit Studio [version].app/Contents/Java/configuration/client.properties).
    • Descomenta el parámetro cloud.url y establécelo en la URL regional.
    • Guarda el archivo y reinicia Design Studio.

Instalación e inicio

macOS: Error "Client Properties Do Not Exist" al iniciar

• Síntoma: Design Studio no se inicia en macOS con un error que indica que las propiedades del cliente no existen.
• Posible causa: Design Studio se inició directamente desde la imagen de disco (.dmg) en lugar de desde la carpeta Applications. La aplicación debe copiarse a la carpeta Applications antes de poder localizar sus archivos de configuración.
• Resolución:
  1. Cierra Design Studio si se está ejecutando.
  2. Abre el archivo instalador .dmg.
  3. Arrastra el icono de Jitterbit Studio al acceso directo de la carpeta Applications en la ventana del instalador.
  4. Inicia Design Studio desde la carpeta Applications (o desde Spotlight/Launchpad), no desde la imagen de disco.

Design Studio marcado como software malicioso en macOS Sequoia

• Síntoma: En macOS 15 (Sequoia), macOS muestra una advertencia de que Design Studio es software malicioso e impide que se abra.
• Causa posible: macOS Gatekeeper advierte sobre aplicaciones que no están certificadas por Apple y se distribuyen fuera de la Mac App Store. Como Design Studio se distribuye desde la página Descargas del portal Harmony, macOS reporta que no puede verificarlo en busca de software malicioso. Este es el comportamiento estándar de macOS, no un problema real con el instalador.
• Resolución:
  1. Confirma que Design Studio se descargó desde la página oficial Descargas del portal Harmony.
  2. Si ves la advertencia de software malicioso para una instalación descargada desde el portal, la advertencia se puede descartar: no indica un riesgo de seguridad real con el instalador de Jitterbit.

Problemas de visualización

Interfaz borrosa o pequeña en pantallas de alta densidad de Windows 10

• Síntoma: Los elementos de Design Studio aparecen borrosos o demasiado pequeños al ejecutarse en Windows 10 con una pantalla de alto DPI, como un monitor 4K.
• Causa posible: Una configuración de escalado de DPI predeterminada de Windows 10 que no es compatible con Design Studio.
• Resolución: Para los pasos de resolución, consulta Error de escalado de pantalla de alta densidad de Windows 10.

Rendimiento

Tiempo de carga prolongado del proyecto al usar un proxy

• Síntoma: Abrir un proyecto de Design Studio tarda varios minutos o más al conectarse a través de un proxy. Esto puede ir acompañado de un error como:

  Message: Unable to load image icon at this address: https://citizen.jitterbit.eu/v1/endpoints/s3images/financialforce.png
  Details: Can't get input stream from URL!
  

• Causa posible: El retraso generalmente se debe a que Design Studio intenta obtener iconos de recetas de Citizen Integrator a través de un proxy que no puede alcanzar el servidor de imágenes externo.

• Resolución: Para los pasos de resolución, consulta Tiempos de carga prolongados al usar un proxy.

Transformaciones

La transformación con un script falla con error /PRESCRIPT/ node

• Síntoma: Una transformación que usa un script falla en tiempo de ejecución con:

  Can not find target node (/PRESCRIPT/).
  The structure may have changed so try to open the transformation 'example' and refresh the structure trees.
  

• Causa posible: La estructura XML interna de la transformación se ha vuelto inconsistente con el esquema de destino actual, típicamente después de un cambio de esquema.

• Resolución:
  1. Abre la transformación que falla en Design Studio.
  2. En el lado Destino, haz clic en el botón de actualización en la parte superior del árbol de estructura. Esto relee el esquema y reconstruye la estructura interna de la transformación.
  3. Guarda e implementa la transformación.

Unmap no desmapea un campo cuando se usa junto con RunScript

• Síntoma: La expresión de mapeo de un campo de destino involucra tanto RunScript como Unmap, pero el campo no se desmapea. Para un destino JSON o XML, el campo aparece en la salida con un valor null en lugar de ser omitido.

• Posibles causas:

  • RunScript precede a Unmap en la misma expresión de mapeo (por ejemplo, RunScript("<TAG>script:MyScript</TAG>"); Unmap();). En versiones de agente anteriores a la 12.9, esta combinación no desmapeaba el campo.
  • Se llama a Unmap desde dentro del script invocado por RunScript, en lugar de directamente en la propia expresión de mapeo del campo de destino. RunScript devuelve el resultado del script llamado como una cadena en lugar de propagar una señal de desmapeo hacia el mapeo, por lo que llamar a Unmap desde dentro del script llamado no tiene efecto, en cualquier versión de agente, independientemente de cualquier lógica condicional alrededor de la llamada. Este es el comportamiento esperado.

• Resolución:

  • Si se llama a RunScript y Unmap directamente en la expresión de mapeo del campo de destino, actualiza el agente privado a la versión 12.9 o posterior.

  • Si se llama a Unmap desde dentro del script invocado por RunScript, mueve la llamada a Unmap fuera del script llamado y hacia la propia expresión de mapeo del campo de destino, por ejemplo:

    RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
    

Las funciones de fecha devuelven medianoche en lugar de un valor de solo fecha

• Síntoma: Después de actualizar a la versión 12.8 del agente o posterior, ConvertTimeZone, Date o GeneralDate devuelve una cadena de fecha y hora completa (por ejemplo, 2026-01-01 00:00:00) para una entrada de exactamente medianoche, en lugar de una cadena de solo fecha (2026-01-01), lo que puede romper la lógica descendente que espera el formato más corto. CVTDate no se ve afectada.
• Posible causa: Con agentes versión 12.8 y posterior, estas funciones tratan medianoche (00:00:00) como un valor de hora válido y lo preservan en el valor devuelto, de la misma manera que cualquier otra hora. Anteriormente, un valor de exactamente medianoche se truncaba a una cadena de solo fecha, mientras que cualquier otra hora se preservaba correctamente.
• Resolución: Si la lógica descendente requiere un valor de solo fecha, utiliza FormatDate para formatear explícitamente el resultado en lugar de depender del formato de salida predeterminado de la función.

La marca de orden de bytes (BOM) en un archivo de origen se pasa al valor del primer registro

• Síntoma: Cuando un archivo de origen (por ejemplo, un archivo CSV) comienza con una marca de orden de bytes (BOM) UTF-8, el primer campo del primer registro en la salida de transformación contiene un carácter adicional o inesperado que no forma parte de los datos de origen, en lugar del valor esperado. Los archivos exportados como CSV UTF-8 desde Microsoft Excel comúnmente incluyen este BOM.
• Posible causa: Design Studio lee el contenido de un archivo de origen tal como está y no detecta ni elimina un BOM inicial. Los bytes sin procesar del BOM se convierten en parte del valor del primer campo una vez que el archivo se analiza en registros.
• Resolución: Inspecciona el valor del campo afectado para identificar los caracteres exactos producidos por el BOM, luego mapea el campo utilizando Replace para eliminarlos. En una versión anterior, donde UTF-8 no es el predeterminado, también puedes establecer explícitamente la codificación de caracteres a UTF-8 antes de que se ejecute la actividad de origen, por ejemplo $jitterbit.source.text.character_encoding = "utf-8";. Design Studio versión 11.63 y posterior, y agente versión 12.7 y posterior, utilizan UTF-8 de forma predeterminada.

Gestión de proyectos

No se recomienda almacenar proyectos de Design Studio en un recurso compartido de red

• Síntoma: Un proyecto de Design Studio almacenado en un recurso compartido de red (en lugar de almacenamiento local o en la nube de Harmony) presenta pérdida de datos, donde los cambios de la interfaz de usuario no persisten después de reabrir el proyecto, o el rendimiento es notablemente más lento de lo esperado.
• Causa posible: Jitterbit no recomienda almacenar espacios de trabajo de proyectos de Design Studio en un recurso compartido de red. El almacenamiento en recursos compartidos de red carece de los mecanismos de bloqueo de archivos que Design Studio requiere, lo que genera guardados inconsistentes y posible pérdida de datos.
• Resolución: Mueve el espacio de trabajo del proyecto al almacenamiento local o utiliza almacenamiento en la nube de Harmony en lugar de un recurso compartido de red.

La descarga del proyecto falla con el error Invalid XML character

• Síntoma: La descarga de un proyecto a Design Studio falla con un error que indica que se encontró un carácter XML inválido en el contenido del elemento, por ejemplo:

  An invalid XML character (Unicode: 0x15) was found in the element content of the document
  

  o:

  org.xml.sax.SAXParseException; lineNumber: 17499; columnNumber: 21; An invalid XML character (Unicode: 0x5) was found in the element content of the document.
  

• Causa posible: Los metadatos del proyecto contienen un carácter de control (como 0x05 o 0x15) que no es válido en XML. Esto puede resultar de una URL de punto de conexión corrupta o de caracteres inusuales pegados en scripts, notas u otros campos de texto.

• Resolución:
  1. Abre el proyecto en Design Studio (o utiliza una copia de seguridad local reciente) para inspeccionar los metadatos.
  2. Revisa las URL de puntos de conexión, scripts y notas para detectar caracteres invisibles o inusuales y elimínalos o reemplázalos. El número de línea en el mensaje de error puede ayudar a localizar el área afectada en el XML exportado.
  3. Guarda e implementa el proyecto corregido, luego reintenta la descarga desde Design Studio.
  4. Si no se puede identificar el contenido problemático, contacta al soporte de Jitterbit con el mensaje de error completo e ID del proyecto para una posible reparación de metadatos en el backend.

Componentes del proyecto faltantes después de descargar o importar

• Síntoma: Al abrir o importar un proyecto se muestran operaciones en la lista pero no aparecen componentes (transformaciones, scripts, esquemas), o un archivo de exportación del proyecto .json falla al importar. La causa suele ser un único componente corrupto en la exportación del proyecto que interrumpe el análisis de todo el archivo.
• Causa posible: Un componente dentro de la exportación del proyecto tiene JSON mal formado, como un cuerpo vacío o caracteres inusuales que invalidan el archivo.
• Resolución:
  1. Exporta el proyecto desde el portal de Harmony para producir un archivo .json.
  2. Abre el archivo .json en un editor de texto e inspecciona el array components para buscar entradas que parezcan vacías, mal formadas o que contengan caracteres inusuales.
  3. Elimina el objeto JSON completo del componente sospechoso del array components.
  4. Guarda el archivo e impórtalo nuevamente a Harmony.
  5. Si la corrupción no es identificable, envía la exportación del proyecto al soporte de Jitterbit para su análisis.

Operaciones o transformaciones duplicadas aparecen en un proyecto descargado

• Síntoma: Algunos usuarios que descargan el mismo proyecto ven operaciones o transformaciones duplicadas con nombres y esquemas idénticos, y esos duplicados se marcan como inválidos (marcados en rojo) en Design Studio. Otros usuarios ven una versión limpia del mismo proyecto.
• Causa posible: El proyecto se migró a nivel de operación (en lugar de a nivel de proyecto), y la migración agregó copias duplicadas de dependencias (como transformaciones) al proyecto original.
• Resolución:
  1. Haz una copia de seguridad del proyecto antes de hacer cambios.
  2. Identifica las operaciones o transformaciones duplicadas. Elimina los duplicados mientras retienes los originales.
  3. Implementa el proyecto limpio. Todos los usuarios que descarguen nuevamente el proyecto recibirán la versión limpia.
  4. Para evitar esto en el futuro, evita usar migración a nivel de operación en un proyecto que ya contiene los componentes de origen. Utiliza migración a nivel de proyecto o migra selectivamente solo las dependencias que no estén presentes.

La importación de proyecto de Salesforce falla con un requisito de versión incorrecto

• Síntoma: La importación o apertura de un proyecto con un endpoint de Salesforce falla con un error como:

  The Jitterpak requires version 12.7.0.0 or higher. The Studio is currently running version [your Design Studio version]. This means that the Jitterpak cannot be opened by this Studio.
  

  Esto puede ocurrir incluso en una versión actual y compatible de Design Studio, porque Design Studio nunca ha tenido una versión 12.x.

• Posible causa: El proyecto se exportó desde Design Studio 11.63 o 11.64. Estas versiones marcan un proyecto que contiene un endpoint de Salesforce con una versión requerida incorrecta (12.7.0.0) en lugar de la versión mínima correcta. Design Studio 11.64.1 y versiones posteriores exportan la versión requerida correcta.

• Resolución:

  • Si el proyecto se exportó a un archivo .jpk local:

    1. Cambia el nombre del archivo .jpk a .zip y luego extráelo.
    2. En environment.properties, cambia el valor de requires-version para que coincida con tu versión instalada de Design Studio, por ejemplo: requires-version=11.63.0.0.
    3. En jitterpak.properties, cambia el valor de required_version al valor codificado correspondiente. Para Design Studio 11.63.0.0, usa required_version=110630000000000. Para cualquier otra versión, exporta un nuevo proyecto vacío desde tu Design Studio instalado y copia los valores de required_version y requires-version de los archivos de ese proyecto en su lugar.
    4. Comprime los archivos extraídos nuevamente en un archivo .zip, cambia su nombre a .jpk e impórtalo.

    Estos pasos corrigen solo el archivo .jpk que editas. Reexportar el proyecto desde Design Studio 11.63 o 11.64 escribe nuevamente el requisito de versión incorrecto, así que actualiza a Design Studio 11.64.1 o posterior para evitar esto.

  • Si el error ocurre al descargar o abrir un proyecto implementado en la nube de Harmony en lugar de al importar un archivo .jpk local:

    1. Actualiza a Design Studio 11.64.1 o posterior.
    2. Contacta al soporte de Jitterbit para solicitar la corrección del backend al requisito de versión almacenado del proyecto, que no está disponible en la interfaz de usuario de Design Studio. Solicita la corrección solo después de actualizar: abrir o reexportar el proyecto con una versión anterior afectada después puede escribir nuevamente el requisito de versión incorrecto en el proyecto.

Notificaciones

La falla de SOAP no se implementa cuando se configura para activar un correo electrónico directamente

• Síntoma: Configurar una falla de SOAP para activar directamente una notificación por correo electrónico falla en la implementación o no funciona como se esperaba.
• Posible causa: Implementar una operación en la que una falla de SOAP activa directamente un mensaje de correo electrónico puede producir un error.
• Resolución:
  1. Configura la falla de SOAP para activar una operación en su lugar.
  2. En esa operación, usa la función SendEmailMessage en un script para enviar el correo electrónico de notificación.

Conector de base de datos

Base de datos: Conexión bloqueada por política de seguridad

• Síntoma: Una prueba de conexión de origen o destino de base de datos falla con:

  HttpErrorResponse: The database connection could not be established due to a security policy violation.
  

  con una línea de detalles que nombra una conexión de loopback:

  Details: java.lang.IllegalArgumentException - JDBC connections to loopback addresses are not permitted.
  

o un parámetro de cadena de conexión específico:

Details: java.lang.IllegalArgumentException - JDBC connection parameter 'allowmultiqueries' cannot be enabled.

• Posible causa: El agente versión 12.10 y posteriores restringen ciertas conexiones de base de datos y parámetros de cadena de conexión por defecto, por seguridad. Esto incluye conexiones a localhost o 127.0.0.1, y parámetros específicos de cadena de conexión para los controladores MySQL, PostgreSQL, Oracle y SQL Server. Una conexión que funcionaba antes puede fallar después de actualizar un agente privado a la versión 12.10, porque la restricción se aplica por defecto aunque la sección [JdbcSecurity] no se agregue automáticamente a un archivo jitterbit.conf existente.

• Resolución: En un agente privado, configura la sección [JdbcSecurity] del archivo de configuración del agente (jitterbit.conf) para permitir la conexión o parámetro específico que necesitas, luego reinicia el agente.

Orígenes FTP y de archivos

Las transferencias de archivos se repiten inesperadamente

• Síntoma: Una operación retransfiere un archivo de origen que ya se procesó en una ejecución anterior.
• Posible causa: Design Studio rastrea tres criterios para determinar si un archivo ya se ha transferido: nombre de archivo, fecha de modificación e ID de operación. Si alguno de estos valores ha cambiado desde la última transferencia, Design Studio trata el archivo como nuevo y lo transfiere nuevamente.
• Resolución: Para evitar que un archivo específico se retransfiera, elimina su entrada de la lista de historial de transferencias: selecciona la casilla junto a la entrada en el panel inferior y haz clic en Eliminar.

FTP: Modo pasivo y restricciones de firewall de puertos altos

• Síntoma: Un origen FTP se conecta exitosamente desde una estación de trabajo pero falla cuando la operación se ejecuta en el agente privado, o las transferencias de archivos agotan el tiempo de espera a pesar de que el agente puede alcanzar el servidor FTP.
• Posible causa: El modo pasivo FTP utiliza puertos de números altos asignados dinámicamente para transferencias de datos. Los firewalls que restringen conexiones salientes a puertos conocidos bloquean estas conexiones de canal de datos, incluso cuando el canal de control (puerto 21) está abierto.
• Resolución:
  • Confirma que Modo Pasivo esté habilitado en la configuración del origen FTP (está habilitado por defecto).
  • Trabaja con tu administrador de red para abrir el rango de puertos de números altos utilizado por tu servidor FTP para conexiones de datos pasivos en el firewall entre el host del agente privado y el servidor FTP.

FTP: Las rutas de carpetas de éxito y error están en el agente, no en el servidor FTP

• Síntoma: Los archivos no aparecen en la carpeta de éxito o error configurada después de que se ejecuta una operación FTP, o las rutas parecen resolverse a ubicaciones inesperadas.
• Posibles causas:
  • Los campos de ruta de carpeta de éxito y carpeta de error en un origen FTP se refieren a directorios en la máquina del agente privado, no en el servidor FTP remoto. Las rutas relativas se interpretan en relación con el sistema de archivos del host del agente.
  • Las variables de palabras clave de nombre de archivo no se resuelven en estos campos.
• Resolución:
  • Ingresa rutas absolutas en el host del agente privado para los campos de carpeta de éxito y error (por ejemplo, C:\Jitterbit\processed\ en Windows o /var/jitterbit/processed/ en Linux).
  • No utilices palabras clave de nombre de archivo ni caracteres especiales como * en estos campos de ruta.
  • Confirma que la cuenta de servicio del agente tenga permisos de escritura en los directorios configurados.

FTP: No se puede analizar el listado de directorios

• Síntoma: Una fuente FTP no puede listar archivos, o faltan archivos conocidos de la fuente aunque existan en el servidor FTP.
• Causa posible: Algunos servidores FTP devuelven listados de directorios en un formato no estándar que Design Studio no puede analizar con su analizador predeterminado.
• Resolución:
  • En la configuración de la fuente FTP, habilita List only filenames (Listar solo nombres de archivo). Esto hace que la fuente use el comando NLST, que devuelve solo nombres de archivo en lugar de un listado de directorio completo y es más ampliamente compatible entre servidores FTP.
  • Alternativamente, establece la variable de Jitterbit jitterbit.source.ftp.enable_regex_parser en true antes del paso de lectura FTP para habilitar un analizador de listado más flexible.

Destino FTP: Use FTP Rename no funciona con operaciones de archivo SFTP

• Síntoma: Los archivos escritos en un servidor SFTP usando un destino FTP con Use FTP Rename habilitado fallan o no se escriben correctamente cuando el tipo de operación es archivo.
• Causa posible: La opción Use FTP Rename no funciona al escribir en un servidor SFTP en una operación de archivo.
• Resolución: En la configuración del destino FTP, desactiva la casilla Use FTP Rename cuando el servidor de destino es un servidor SFTP y la operación escribe un archivo.

Destino FTP: Auto Create Directories no es confiable

• Síntoma: Una operación de destino FTP falla porque no existe un directorio de destino, aunque Auto Create Directories esté habilitado.
• Causa posible: Es un problema conocido que la opción Auto Create Directories funciona de manera inconsistente. Dependiendo del servidor FTP en particular, es posible que no se cree el directorio.
• Resolución:
  • Crea manualmente los directorios requeridos en el servidor FTP antes de ejecutar la operación.
  • Si usas Auto Create Directories, confirma que el directorio se haya creado antes de depender de él en producción.

Fuente File Share: No se pueden recuperar archivos individuales mayores a 2 GB

• Síntoma: La recuperación de un archivo grande de una fuente File Share falla, aunque el archivo existe y la conexión de la fuente está configurada correctamente.
• Causa posible: Las fuentes File Share tienen una limitación conocida donde es posible que no se puedan recuperar archivos individuales mayores a 2 GB.
• Resolución: Divide los archivos mayores a 2 GB en segmentos más pequeños antes de colocarlos en el recurso compartido de archivos para su recuperación.

Fuente HTTP

La prueba de conexión falla aunque el endpoint sea accesible

• Síntoma: La prueba de una conexión de fuente HTTP falla con un error de conexión o autorización, pero se confirma que el endpoint es accesible y devuelve datos cuando se accede directamente en un navegador o cliente API.
• Causa posible: El botón Test Connection (Probar conexión) en la configuración de la fuente HTTP envía una solicitud HTTP HEAD. Algunos servidores no admiten el método HEAD y devuelven un error 405 o similar, aunque las solicitudes GET y POST tengan éxito.
• Resolución:
  1. Si se confirma que el endpoint es accesible en un navegador o mediante una solicitud GET/POST directa, se puede descartar la prueba de conexión fallida. Procede con la implementación y ejecución de la operación para verificar la conectividad real.
  2. Si la operación también falla en tiempo de ejecución, investiga más usando los registros de operación.

Conector de NetSuite

Error de URL del centro de datos: Usar URL WSDL específica de la cuenta

• Síntoma: Un endpoint de NetSuite que anteriormente se conectaba correctamente ahora falla con:

  Connector Error: Error getting the data center URL.
  ...
  In this account, you must use account-specific domains with this SOAP web services endpoint.
  

  o:

  You are not requesting the correct data center for your company.
  

• Causa posible: NetSuite ya no acepta URLs WSDL genéricas (por ejemplo, https://webservices.netsuite.com/...) ni URLs WSDL específicas del centro de datos (por ejemplo, https://webservices.na3.netsuite.com/...). El endpoint debe usar una URL WSDL específica de la cuenta.

• Resolución:
  1. En NetSuite, ve a Setup > Company > Company Information y abre la pestaña Company URLs para encontrar el dominio específico de la cuenta.
  2. Construye la URL WSDL específica de la cuenta con el formato https://<account-id>.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl.
  3. Actualiza el campo WSDL Download URL en la configuración del endpoint de NetSuite con la URL específica de la cuenta.
  4. Para obtener instrucciones completas, consulta URL WSDL específica de la cuenta de NetSuite.

Los usuarios con TFA no deben usar el tipo de autenticación SSO

• Síntoma: Un endpoint de NetSuite configurado con autenticación de inicio de sesión único (SSO) falla o se comporta de manera inesperada para un usuario que tiene autenticación de dos factores (TFA o 2FA) habilitada en su cuenta de NetSuite.
• Causa posible: Los usuarios de NetSuite con TFA habilitado no deben usar el tipo de autenticación SSO al configurar un endpoint de NetSuite. Esta combinación puede causar que el endpoint falle. NetSuite también está eliminando gradualmente el tipo de autenticación SSO.
• Resolución:
  1. Habilita la autenticación basada en tokens (TBA) en la cuenta de NetSuite.
  2. Reconfigura el endpoint de NetSuite para usar TBA en lugar de SSO.

TBA: Error INSUFFICIENT_PERMISSION en tiempo de ejecución a pesar de una prueba de conexión exitosa

• Síntoma: Un endpoint de NetSuite configurado con autenticación basada en tokens (TBA) prueba la conexión exitosamente, pero las operaciones fallan en tiempo de ejecución con:

  INSUFFICIENT_PERMISSION
  

• Causa posible: El rol utilizado para generar los tokens de acceso de TBA no tiene permisos suficientes para las operaciones que se están ejecutando. La prueba de conexión se realiza correctamente incluso con un rol con permisos insuficientes, pero las verificaciones de permisos en tiempo de ejecución fallan.

• Resolución:
  1. En NetSuite, cambia a un rol de Acceso Total o Administrador al generar los tokens de acceso, o agrega los permisos requeridos al rol actual.
  2. Regenera los tokens de acceso usando el rol actualizado y reconfigura el endpoint de NetSuite.

El menú desplegable de búsqueda guardada está vacío cuando el objeto tiene más de 1,000 búsquedas guardadas

• Síntoma: El menú desplegable de búsqueda guardada en la configuración de la actividad de NetSuite no se completa con ninguna opción, aunque existan búsquedas guardadas para el objeto en NetSuite.
• Causa posible: NetSuite impone un límite de 1,000 registros en las solicitudes de API. Si un objeto tiene más de 1,000 búsquedas guardadas, la solicitud de API para recuperarlas excede este límite y no devuelve resultados, dejando el menú desplegable vacío.
• Resolución: En NetSuite, elimina o archiva las búsquedas guardadas que ya no se usan para reducir el recuento total por debajo de 1,000 para el objeto afectado. El menú desplegable se completará una vez que se reduzca el recuento. Para obtener más detalles, consulta Limitaciones de búsqueda guardada de NetSuite.

Los valores NULL o en blanco no se pueden pasar a campos personalizados de NetSuite

• Síntoma: Asignar un valor NULL o en blanco (cadena vacía) a un campo personalizado de NetSuite no borra el campo en NetSuite.
• Causa posible: La API de NetSuite no acepta valores NULL o en blanco para campos personalizados a través del enfoque estándar de asignación de campos.
• Resolución: Para pasar valores NULL o en blanco a un campo personalizado, asigna el campo de origen a los campos secundarios externalId y name del nodo de destino del campo personalizado en la transformación. Para más detalles, consulta Pasar valores nulos a campos personalizados.

Segmentos personalizados no mostrados en la configuración de actividad

• Síntoma: Los segmentos personalizados no aparecen en la pantalla de configuración de actividad de NetSuite cuando se espera que estén disponibles para asignación.
• Causa posible: La cuenta de usuario de NetSuite configurada en el endpoint no tiene permisos suficientes para acceder al segmento personalizado o al objeto con el que está asociado.
• Resolución:
  1. En NetSuite, verifica que la cuenta de usuario configurada en el endpoint de NetSuite tenga los permisos apropiados para interactuar con el segmento personalizado y su objeto asociado.
  2. Si los permisos son insuficientes, actualiza el rol de usuario en NetSuite para incluir el acceso requerido al segmento personalizado.

Conector SAP

IDocs no encontrados cuando una operación programada se ejecuta en un agente diferente

• Síntoma: En un grupo multiagente que utiliza procesamiento de IDoc de almacenamiento y reenvío, la operación programada que busca archivos IDoc almacenados no encuentra archivos para procesar en algunas ejecuciones, y el procesamiento de IDoc se retrasa u ocurre fuera de orden.
• Causa posible: En el procesamiento de almacenamiento y reenvío, el Escucha de Eventos de SAP almacena cada IDoc recibido en el sistema de archivos local del agente que lo recibió. Una operación separada con una programación rápida busca y procesa esos archivos, pero Harmony puede enviar esa operación programada a cualquier agente del grupo. Cada agente procesa solo los archivos almacenados en sí mismo, por lo que los archivos almacenados en un agente no se procesan hasta que la programación seleccione nuevamente ese agente.
• Resolución: Cada agente procesa sus propios archivos almacenados la próxima vez que la operación programada se ejecute en él, por lo que los archivos se procesan eventualmente. Si los IDocs deben procesarse en un orden garantizado, o sin esperar la próxima ejecución programada del agente de almacenamiento, escribe los archivos IDoc en un recurso compartido al que todos los agentes puedan acceder, como un sitio FTP, un sistema de archivos compartido o una base de datos. Ten en cuenta que un almacén de datos externo añade un punto de fallo; de lo contrario, los clústeres de agentes se utilizan para conmutación por error y equilibrio de carga.

Los envíos masivos de IDocs pueden exceder los límites de conexión del endpoint de destino

• Síntoma: Después de que una operación masiva grande de SAP envía miles de IDocs, las operaciones contra un sistema de destino descendente (como Salesforce) fallan intermitentemente con errores de límite de conexión o inicio de sesión.
• Causa posible: Los IDocs se envían de forma asincrónica. Cuando una actualización masiva genera miles de IDocs, todos ellos intentan activar sus operaciones descendentes simultáneamente. Sistemas como Salesforce aplican límites de conexión de API concurrentes, y una avalancha repentina de operaciones activadas por IDoc puede exceder esos límites.
• Resolución:
  • Utiliza un patrón de almacenamiento y reenvío: configura el escucha de IDoc para escribir IDocs entrantes en archivos temporales, luego utiliza una operación programada para procesarlos en lotes controlados a una velocidad predecible.
  • Revisa los límites de conexión concurrente y llamadas de API del endpoint de destino y configura la operación de Design Studio para mantenerse dentro de esos límites limitando el número de operaciones simultáneas.

Carga útil de IDoc de SAP perdida cuando el endpoint de destino es inaccesible

• Síntoma: El SAP Event Listener recibe un IDoc, pero los datos no llegan al endpoint de destino y no se pueden recuperar.
• Causa posible: En el procesamiento directo, si el endpoint de destino es inaccesible cuando se procesa el IDoc, la carga útil no se entrega y se pierde permanentemente. No existe un mecanismo de reintento automático en el procesamiento directo.
• Resolución: Utiliza el procesamiento de almacenamiento y reenvío en su lugar: configura la primera operación para escribir el IDoc entrante en un archivo temporal, luego usa una operación programada para procesar el archivo. Si el destino es inaccesible, el archivo se retiene y se reprocesa en la siguiente ejecución programada. Para obtener orientación sobre la implementación del procesamiento de almacenamiento y reenvío, consulta Prácticas recomendadas para SAP.

Almacenamiento y reenvío de IDoc de SAP: Archivos temporales eliminados después de 24 horas

• Síntoma: En un flujo de trabajo de IDoc de almacenamiento y reenvío, los archivos temporales que no han sido procesados desaparecen del directorio de almacenamiento antes de que se ejecute la operación de procesamiento.
• Causa posible: De forma predeterminada, los archivos IDoc temporales en el procesamiento de almacenamiento y reenvío se eliminan automáticamente después de 24 horas. Si la operación de procesamiento programada no se ejecuta dentro de ese período (por ejemplo, debido a un tiempo de inactividad del agente), los archivos se eliminan antes de que se puedan procesar.
• Resolución:
  • Asegúrate de que la operación de procesamiento programada se ejecute al menos una vez cada 24 horas para procesar los archivos antes de que expiren.
  • Alternativamente, aumenta el período de retención si se requiere una ventana más larga. Para obtener más detalles, consulta Prácticas recomendadas para SAP.

La operación BAPI se ejecuta correctamente pero la transacción no se confirma en SAP

• Síntoma: La ejecución de un BAPI parece ejecutarse sin errores, pero la transacción esperada no aparece en SAP.
• Causa posible: El conector de SAP emite una confirmación de transacción BAPI solo cuando el BAPI devuelve un tipo de respuesta S (Éxito). Si el BAPI devuelve un tipo de respuesta I (Información), E (Error) o W (Advertencia), no se emite confirmación y la transacción no se guarda en SAP.
• Resolución:
  1. Verifica el campo TYPE del nodo RETURN en la respuesta del BAPI para confirmar el tipo de respuesta que se devuelve.
  2. Si utilizas un BAPI personalizado, actualízalo para devolver un tipo de respuesta S cuando la transacción deba confirmarse. Para obtener más detalles, consulta Solución de problemas de confirmaciones de BAPI.

SAP Event Listener no recoge IDocs en Windows

• Síntoma: El servicio SAP Event Listener se está ejecutando, el sistema SAP reporta que los IDocs salientes se enviaron correctamente, pero no se activan operaciones. Los registros del agente muestran errores de conexión para el ID del programa RFC, como:

  serverException occured on [Program ID] connection null
  

• Posible causa: El archivo de servicios de Windows en el host del agente no contiene una entrada para el servicio de puerta de enlace SAP. Sin esta entrada, el escucha del ID de programa RFC no puede resolver el nombre de host y puerto de la puerta de enlace SAP, lo que impide que los iDocs se entreguen a Design Studio.

• Resolución:

  1. En el host de Windows que ejecuta el agente privado, abre %WINDIR%\System32\drivers\etc\services como administrador.

  2. Agrega las siguientes líneas:

     sapgw00 3300/tcp
     sapgw00 3300/udp
     

  3. Guarda el archivo, reinicia el servicio SAP Event Listener y el agente, y vuelve a probar enviando un IDoc desde SAP.

El nombre de servicio sapgw00 y el puerto 3300 corresponden al servicio de puerta de enlace SAP predeterminado para el número de sistema 00. Si tu sistema SAP utiliza un número de sistema diferente, ajusta las entradas en consecuencia (por ejemplo, sapgw01 3301/tcp y sapgw01 3301/udp para el número de sistema 01).