Saltar al contenido

Solución de problemas de conectores en Jitterbit Studio

Esta guía cubre errores y comportamientos inesperados que son específicos de cada conector de Jitterbit Studio, organizados por conector. Solo enumera los conectores que tienen problemas conocidos específicos del conector para documentar, no todos los conectores disponibles. Para ver la lista completa de conectores, consulta Conectores. Comienza con los pasos de diagnóstico a continuación, luego encuentra tu conector en la sección correspondiente.

Para problemas que no son específicos de un conector, como una operación que no se ejecuta o un problema con una transformación, script o función, consulta Solución de problemas de operaciones. Para problemas de agentes privados, como un agente que está sin conexión, en mal estado o lento (lo que puede detener la ejecución de operaciones), consulta Solución de problemas de agentes privados.

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

Todas las entradas de solución de problemas en esta página

Pasos de diagnóstico

Estos pasos se aplican a la mayoría de las fallas relacionadas con conectores y son el punto de partida recomendado antes de investigar un error específico del conector.

Prueba la conexión

En la configuración de conexión, haz clic en el botón Test para confirmar que la conexión se establece correctamente. Al hacer clic en Test también se descarga la versión más reciente del conector al agente, a menos que esté habilitada la política organizativa Disable Auto Connector Update.

Actualiza los metadatos de conexión y los esquemas de actividad

Muchos problemas de conector, como objetos faltantes, una lista de campos desactualizada o un esquema que ya no coincide con el endpoint, se deben a metadatos en caché. Después de cualquier cambio en el lado del endpoint (campos nuevos, cambio de versión de API o cambio de permisos), vuelve a abrir la actividad afectada y haz clic en el icono de actualización (Actualizar) para recargar objetos y esquemas desde el endpoint.

Confirma la disponibilidad del conector y mantenlo actualizado

La columna Disponibilidad del agente en la lista de conectores muestra si un conector requiere un agente privado.

Los conectores se lanzan y actualizan según el cronograma de lanzamientos de Jitterbit, de manera independiente al agente. En agentes privados, probar una conexión descarga la versión más reciente del conector (consulta Prueba la conexión arriba), a menos que esté habilitada la política de organización Inhabilitar actualización automática de conectores. Para actualizar los conectores de un grupo de agentes en cualquier momento, incluso cuando esa política esté habilitada, selecciona Acción > Actualizar conectores para el grupo en la página Agentes de la Consola de administración.

Habilita el registro detallado del conector

Cuando Jitterbit Support lo indique, habilita el registro detallado del conector en el agente privado para capturar detalles a nivel de conector, luego reproduce el problema y revisa los registros. El registro detallado utiliza una entrada de registrador específica del conector; la línea exacta para agregar a logback.xml se proporciona en la sección Solución de problemas de la página de documentación propia de ese conector, en Conectores.

Configuración de conexión

Propiedades de configuraciones avanzadas: Las variables que contienen JSON sin formato deben escaparse

  • Síntoma: Muchos conectores incluyen una tabla de Propiedades de configuraciones avanzadas para parámetros de conexión opcionales. Las variables utilizadas en estos campos que contienen JSON sin formato deben tener el JSON escapado; pasar JSON sin formato sin escapar a través de una variable hace que el valor del campo sea malformado.
  • Posible causa: Los campos en la tabla de Propiedades de configuraciones avanzadas no admiten variables que contengan objetos JSON sin escapar.
  • Resolución:
    • Antes de pasar contenido JSON a través de una variable a un campo de Propiedades de configuraciones avanzadas, escapa el JSON. Por ejemplo, {"success": "true"} debe escaparse como {\"success\": \"true\"} antes de asignarlo a la variable.
    • Si ingresas el valor JSON directamente en el campo (no a través de una variable), no se requiere escapar.
    • Las variables en campos de Propiedades de configuraciones avanzadas se rellenan en tiempo de ejecución solo en la versión del agente 10.75 / 11.13 o posterior. Si un valor de variable no aparece en tiempo de ejecución, confirma que el agente cumple con esta versión mínima.

Conector Amazon Bedrock

Amazon Bedrock: Error de modelo "el rendimiento bajo demanda no es compatible"

  • Síntoma: Una actividad de Amazon Bedrock falla con:

    Invocation of model ID <model-name> with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model.

  • Posible causa: Algunos modelos, incluidos los modelos GPT-5.6 de OpenAI, no son compatibles con el rendimiento bajo demanda y requieren la ID de un perfil de inferencia entre regiones en lugar de la ID del modelo que se devuelve en la lista Seleccionar un modelo de la actividad.

  • Resolución:
    1. En la consola de administración de AWS, ve a Amazon Bedrock > Perfiles de inferencia e identifica la ID del perfil de inferencia para el modelo. Por ejemplo, la ID del perfil de inferencia para anthropic.claude-3-5-haiku-20241022-v1:0 en Estados Unidos es us.anthropic.claude-3-5-haiku-20241022-v1:0. Para los modelos GPT-5.6 de OpenAI, los prefijos válidos de ID del perfil de inferencia varían según el modelo y la región (por ejemplo, us. o global.), como us.openai.gpt-5.6-terra o global.openai.gpt-5.6-terra. Para obtener la ID del perfil de inferencia exacta para tu modelo y región, consulta las fichas de modelo de AWS para GPT-5.6 Sol, GPT-5.6 Terra y GPT-5.6 Luna.
    2. Ingresa la ID del perfil de inferencia utilizando la opción Ingresar identificador de modelo en la configuración de la actividad.

Conector Cloud Datastore

La actividad Query Items no devuelve todos los registros coincidentes al filtrar por múltiples valores del mismo campo

  • Síntoma: Una actividad Query Items que se utiliza para buscar varios registros específicos a la vez (por ejemplo, por una lista de valores de Key) devuelve solo un registro, aunque todos los registros existen en el almacenamiento y se pueden confirmar en la página Cloud Datastore de la Consola de Administración.
  • Causa posible: El filtro de la consulta combina múltiples condiciones en el mismo campo (por ejemplo, varios valores de Key diferentes en un solo filtro). Las condiciones de filtro de Cloud Datastore solo se pueden combinar cuando cada condición especifica un campo diferente; un filtro no puede especificar el mismo campo más de una vez, y no se pueden aplicar más de una condición u operador al mismo campo.
  • Resolución: Ejecuta una llamada Query Items separada para cada valor en lugar de combinar múltiples valores del mismo campo en un solo filtro. Para más detalles sobre las condiciones de filtro admitidas, consulta Actividad Query Items.

La actividad Delete Items reporta éxito pero no elimina el registro

  • Síntoma: Una actividad Delete Items de Cloud Datastore reporta éxito en el registro de operaciones, pero el registro de destino aún existe cuando se consulta después.
  • Causa posible: Delete Items identifica registros por el valor de Key (o Alternative Key) del almacenamiento, proporcionado en el array keys o ids de la solicitud. (Ambos arrays aceptan valores de clave o clave alternativa.) Si se proporciona el ID interno del registro en lugar de su valor de clave, ningún elemento coincide, y la actividad reporta éxito sin eliminar nada.
  • Resolución:
    • En la transformación que prepara la solicitud Delete Items, mapea el valor de Key (o Alternative Key) del almacenamiento, no el ID de registro interno.
    • Cuando encadenas desde una actividad Query Items, mapea el valor de key de la respuesta de consulta a la solicitud de eliminación.

Conector Coupa

Coupa: La autenticación por clave de API devuelve 403 Forbidden

  • Síntoma: Una operación del conector Coupa falla con un error Forbidden (403) al utilizar autenticación por clave de API.
  • Causa posible: A partir de la versión Coupa R35 (enero de 2023), las claves de API de Coupa están deprecadas y ya no se admiten para la autenticación. Las conexiones configuradas para utilizar autenticación por clave de API reciben un error 403.
  • Resolución:
    1. En la configuración de conexión de Coupa, cambia de autenticación por clave de API a autenticación OAuth 2.0.
    2. En tu instancia de Coupa, crea una aplicación cliente OAuth 2.0 y obtén las credenciales del cliente.
    3. Actualiza la configuración de conexión con las credenciales de OAuth 2.0, guarda y prueba nuevamente.

Conector de base de datos

Base de datos (JDBC): DBLookup o DBExecute falla con un error de decodificación Base64

  • Síntoma: Una función DBLookup o DBExecute dirigida a una base de datos PostgreSQL o SQL Server a través de un controlador JDBC falla en tiempo de ejecución con:

    Base64 decoding failed. Reason: error:00000000:lib(0)::reason(0)

    Esto ocurre siempre que el valor devuelto se parece a datos codificados en Base64, como un JWT u otro token de acceso, aunque la misma consulta se ejecute correctamente directamente en la base de datos.

  • Causa posible: Las versiones del agente anteriores a la 12.9 pueden intentar incorrectamente descodificar en Base64 un valor de resultado JDBC que coincida con un patrón similar a Base64, independientemente de si el valor es datos codificados en Base64 reales.

  • Solución:

    • Para agentes privados, actualiza a la versión 12.9 o posterior. Los agentes en la nube reciben la actualización automáticamente.
    • Si no puedes actualizar de inmediato, evita desencadenar la verificación de Base64 convirtiendo el valor afectado a hexadecimal en la consulta SQL y luego decodificándolo en un paso de script usando HexToString. Por ejemplo, en PostgreSQL: SELECT encode(<column>, 'hex'). Usa el equivalente en SQL decode(...,'hex') con StringToHex cuando escribas el valor de vuelta en la base de datos.

Base de datos (ODBC): Los caracteres multibyte no se manejan correctamente

  • Síntoma: Al leer o escribir en una base de datos a través del conector de base de datos usando un controlador ODBC, los caracteres multibyte o no ASCII (por ejemplo, caracteres acentuados o no latinos) no se manejan correctamente.
  • Causa posible: La compatibilidad con caracteres multibyte para el conector de base de datos sobre un controlador ODBC no está habilitada de forma predeterminada. La variable de Jitterbit jitterbit.scripting.db.multibyte.enable debe establecerse en true. Esta compatibilidad está disponible en la versión 12.6 del agente y posterior, y no es necesaria cuando se usa un controlador JDBC.

  • Solución:

    1. Confirma que el agente es versión 12.6 o posterior.

    2. Establece la variable jitterbit.scripting.db.multibyte.enable en true antes de que se ejecute la operación de base de datos. Por ejemplo, en un paso de script:

      $jitterbit.scripting.db.multibyte.enable = true;

    Alternativamente, usa un controlador JDBC para la conexión de base de datos, que maneja caracteres multibyte sin necesidad de esta variable.

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

  • Síntoma: Una prueba de conexión del conector 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 nombre una conexión de bucle invertido:

    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.

  • Causa posible: La versión 12.10 del agente y posterior restringe ciertas conexiones de base de datos y parámetros de cadena de conexión de forma predeterminada, por seguridad. Esto incluye conexiones a localhost o 127.0.0.1, y parámetros de cadena de conexión específicos 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 de forma predeterminada 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.

Base de datos: Tiempos de espera de conexión bajo carga

  • Síntoma: Las operaciones de origen o destino de la base de datos fallan intermitentemente bajo carga concurrente pesada, con una excepción similar a:

    java.sql.SQLException: Network error IOException: Connection timed out
Caused by: java.net.ConnectException: Connection timed out

  • Causa posible: Cada operación de base de datos abre una nueva conexión JDBC física y la cierra después, en lugar de reutilizar una existente. Bajo carga concurrente, esto genera suficiente rotación de conexiones contra la base de datos de destino que algunos intentos de conexión se agotan.

  • Resolución: La versión 12.11 del agente y posteriores pueden agrupar y reutilizar conexiones en lugar de abrir y cerrar una para cada operación, reduciendo esta rotación. En un agente privado, establece jdbc.hikari.enabled=true en la sección [SourceTargetPooling] del archivo de configuración del agente (jitterbit.conf), luego reinicia el agente.

Base de datos: Errores de longitud de campo en Insert, Update o Upsert

  • Síntoma: Una actividad Base de datos Insert, Update o Upsert falla con un estado de operación Error cuando un valor de origen asignado es más largo que lo que permite la columna de destino. El registro de operaciones contiene uno de los siguientes:

    One or more values were truncated when inserting and/or updating the field

    Field value too long
FieldName: m_site  Length: 3  Length Allowed: 1

  • Causa posible: De forma predeterminada, si un valor de origen asignado excede la longitud definida de la columna de destino, la actividad rechaza la fila e informa de un estado Error en lugar de truncar el valor.

  • Resolución:
    1. En la configuración de la actividad Insert, Update o Upsert de la base de datos, habilita Permitir truncamiento de campos de caracteres para evitar errores de longitud de campo. Con esta opción habilitada, los valores que exceden la longitud del campo de destino se truncan y la operación informa de un estado Éxito con información en lugar de un estado Error.
    2. Si el truncamiento no es aceptable, recorta o transforma el campo de origen en la asignación de transformación para que los valores nunca superen la longitud de la columna de destino, o amplía la columna de destino en el lado de la base de datos.
    3. Redespliega y vuelve a ejecutar la operación.

Base de datos: Archivo JAR del controlador JDBC sobrescrito en actualizaciones de agente

  • Síntoma: Los archivos JAR del controlador JDBC personalizado instalados para el conector de Base de datos se eliminan o sobrescriben cuando se actualiza el agente.
  • Causa posible: Solo el directorio <JITTERBIT_HOME>/tomcat/drivers/lib/ se preserva en las actualizaciones del agente. Los archivos JAR de controlador personalizado colocados en otros lugares en los directorios del agente son parte de la implementación administrada y se pueden eliminar o sobrescribir durante una actualización.
  • Resolución:
    • Coloca los archivos JAR del controlador JDBC personalizado en <JITTERBIT_HOME>/tomcat/drivers/lib/. Este directorio se preserva durante las actualizaciones del agente.
    • Si los controladores están actualmente en la ubicación incorrecta, muévelos al directorio correcto y reinicia el agente.

Base de datos: Caracteres especiales en nombres de columna causan fallas de consulta

  • Síntoma: Las consultas de Base de datos o transformaciones fallan cuando una tabla de origen tiene nombres de columnas que contienen caracteres especiales como @.
  • Causa posible: Los controladores ODBC no pueden manejar ciertos caracteres especiales en los nombres de columnas de la base de datos.
  • Resolución:
    1. Crear una vista de base de datos en la tabla física que exponga la columna afectada bajo un nombre que no contenga caracteres especiales.
    2. Apuntar la actividad de Base de datos a la vista en lugar de la tabla original.

Base de datos: Sentencia SQL excede el límite de 2,000 caracteres

  • Síntoma: Una actividad de Consulta de Base de datos falla o se trunca cuando la sentencia SQL configurada es muy larga.
  • Causa posible: El campo de sentencia SQL en una actividad de Base de datos Consulta acepta un máximo de 2,000 caracteres.
  • Resolución:
    1. Crear una vista de base de datos que encapsule la lógica de consulta compleja.
    2. Referenciar el nombre de la vista en la actividad de Consulta en lugar de la sentencia SQL completa.

IBM DB2 en iSeries: Falla de conexión JDBC

  • Síntoma: Una conexión de Base de datos a IBM DB2 en iSeries (AS/400 o IBM i) usando un controlador JDBC falla al conectarse.
  • Causa posible: Algunas conexiones a DB2 en iSeries usando un controlador JDBC encuentran problemas que no ocurren con un controlador ODBC.
  • Resolución: Cambiar la conexión para usar un controlador ODBC en lugar de JDBC. Las conexiones ODBC solo se soportan en agentes privados.

IBM DB2: Configuración del controlador JCC JDBC (archivo JAR y licencia obsoletos)

  • Síntoma: Una conexión de Base de datos usando el controlador IBM DB2 JCC JDBC falla con un error que referencia una licencia faltante, o falla o produce errores de compatibilidad con versiones más recientes de DB2.
  • Causas posibles:
    • El archivo de controlador db2jcc.jar implementa la especificación JDBC 3 obsoleta. El archivo db2jcc4.jar actual implementa JDBC 4, que las versiones más recientes de DB2 requieren.
    • El controlador JCC requiere un archivo JAR de licencia separado. El archivo JAR del controlador por sí solo no es suficiente.
  • Resolución:
    • Usar el controlador db2jcc4.jar, no el obsoleto db2jcc.jar. Instalarlo en <JITTERBIT_HOME>/tomcat/drivers/lib/ en el agente privado.
    • Obtener el archivo JAR de licencia de IBM (denominado db2jcc_license_cisuz-XX.jar, donde XX es el número de versión) y copiarlo a <JITTERBIT_HOME>/tomcat/shared/lib/.
    • Alternativamente, utilizar la biblioteca JTOpen de código abierto (también conocida como el controlador AS400), que no requiere el controlador JCC ni un archivo de licencia.

Kerberos: "Could not initialize class KerbAuthentication"

  • Síntoma: Una conexión de Base de datos usando autenticación Kerberos falla con:

    Could not initialize class com.microsoft.sqlserver.jdbc.KerbAuthentication

  • Causa posible: Los archivos de configuración de Kerberos en el host del agente no tienen los permisos de archivo correctos.

  • Resolución:
    1. En el host del agente privado, establecer permisos de archivo en los archivos de configuración de Kerberos (jaas.conf, krb5.conf y el archivo de caché de tickets de Kerberos) en 644:
chmod 644 jaas.conf krb5.conf krb5cc_agent
  1. Reinicia el agente después de aplicar los cambios de permisos.

Kerberos: Errores JGSS o GSS durante la prueba de conexión

  • Síntoma: Una conexión de Base de datos que usa autenticación Kerberos falla con errores que hacen referencia a jgss o gss.
  • Causa posible: La JVM está configurada con -Dsun.security.jgss.native=true, lo que le ordena usar la biblioteca GSSAPI nativa del sistema operativo. En algunos sistemas, esto entra en conflicto con la configuración de Kerberos.
  • Resolución:
    1. Elimina el parámetro -Dsun.security.jgss.native=true de los argumentos de JVM del agente.
    2. En krb5.conf, añade udp_preference_limit = 1 bajo la sección [libdefaults] para forzar TCP en lugar de UDP para el tráfico de Kerberos.
    3. Reinicia el agente.

Microsoft Excel: "La operación debe usar una consulta actualizable"

  • Síntoma: Una actividad Insertar o Actualizar de Base de datos dirigida a un archivo de Microsoft Excel (a través de ODBC) falla con:

    [Microsoft][ODBC Excel Driver] Operation must use an updateable query

  • Causa posible: El controlador ODBC de Excel abre el archivo de Excel en modo de solo lectura de forma predeterminada a menos que la cadena de conexión establezca explícitamente el modo de lectura/escritura.

  • Resolución: En el campo Cadena de conexión de la conexión de Base de datos (ingresado en Configuración opcional con Usar cadena de conexión seleccionado), añade ReadOnly=0; al final de la cadena de conexión para abrir el archivo de Excel en modo lectura/escritura.

MySQL: Acceso denegado a pesar de credenciales correctas

  • Síntoma: La conexión a una base de datos MySQL usando el conector de Base de datos falla con:

    Access denied for user 'root'@'%' to database 'test'

    incluso cuando el nombre de usuario y la contraseña son correctos.

  • Causa posible: MySQL puede otorgar permisos diferentes según la dirección IP del cliente. Una cuenta de usuario puede tener los privilegios requeridos desde direcciones IP específicas pero no desde la dirección IP del agente privado.

  • Resolución:

    • En MySQL, verifica que la cuenta de usuario tenga los permisos necesarios para conexiones desde la dirección IP del agente privado. La sintaxis exacta de permisos varía según la versión de MySQL (consulta la documentación de MySQL o contacta a tu administrador de MySQL), pero generalmente toma la forma:

      GRANT ALL ON database.* TO 'user'@'agent-ip';

    • Prueba la conectividad usando un cliente de MySQL instalado directamente en el host del agente para determinar si el problema es de red o específico de Jitterbit.

MySQL: Habilitar lote no mejora el rendimiento de inserción o actualización

  • Síntoma: Una actividad Insertar o Actualizar de Base de datos que usa el controlador JDBC de MySQL muestra poco o ningún mejora de rendimiento después de habilitar Habilitar lote, incluso con un gran número de registros.
  • Causa posible: De forma predeterminada, el controlador JDBC de MySQL (Connector/J) envía una sentencia por fila independientemente de Habilitar lote, en lugar de un verdadero lote del lado del servidor.
  • Resolución: En el campo Parámetros de cadena de conexión adicionales de la conexión, añade rewriteBatchedStatements=true.

MySQL: El controlador ODBC no aparece en el menú desplegable de Studio

  • Síntoma: Al configurar una conexión a Base de datos a MySQL usando un controlador ODBC en un agente privado, el controlador instalado no aparece en el menú desplegable Controlador en Studio.
  • Causa posible: El administrador ODBC en el host del agente privado no muestra el controlador, generalmente debido a una incompatibilidad entre 32 bits y 64 bits o a una instalación incompleta del controlador.
  • Resolución:
    • En el host del agente privado (Windows), abre Orígenes de datos (ODBC) (bajo Herramientas administrativas) y confirma que el controlador MySQL ODBC aparece en la lista. Para opciones del controlador MySQL, consulta Conectar a MySQL.
    • Confirma que el agente se conecta a la máquina correcta: el controlador ODBC debe estar instalado en el host del agente, no en la máquina del usuario de Studio.

PostgreSQL: Error de incompatibilidad de codificación de cliente

  • Síntoma: Una prueba de conexión del conector de Base de datos a PostgreSQL falla con un error de "incompatibilidad de codificación de cliente".
  • Causa posible: La codificación que utiliza el servidor PostgreSQL difiere de la codificación predeterminada asumida por el controlador ODBC de PostgreSQL.
  • Resolución:
    • En la configuración de conexión de base de datos, agrega ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (sustituyendo la codificación real del servidor) al campo Parámetros adicionales de la cadena de conexión.
    • En Windows, si el servidor utiliza una codificación cirílica como WIN1251, también establece la codificación de cliente a WIN1251 en la configuración del controlador ODBC.

PostgreSQL: Usa el controlador proporcionado por Jitterbit en Linux

  • Síntoma: Las operaciones que utilizan el conector de Base de datos para conectarse a PostgreSQL desde un agente privado en Linux fallan o producen errores, incluso cuando aparentemente hay un controlador instalado.
  • Causa posible: Muchas distribuciones de Linux incluyen un controlador ODBC de PostgreSQL empaquetado con unixODBC que no funciona de forma confiable con Harmony.
  • Resolución: No utilices el controlador PostgreSQL empaquetado con la distribución. En su lugar, utiliza el controlador ODBC de PostgreSQL incluido con la instalación del agente Jitterbit.

SQL Server JDBC: La autenticación integrada de Windows falla

  • Síntoma: Para agentes privados, una conexión a Base de datos a SQL Server usando un controlador JDBC y autenticación integrada de Windows falla con:

    This driver is not configured for integrated authentication. ClientConnectionId:...

    Con el controlador SQL Server MS JDBC, los registros del agente también pueden mostrar:

    java.lang.UnsatisfiedLinkError: no mssql-jdbc_auth-8.2.0.x64 in java.library.path

  • Causas posibles:

    • Usar el controlador SQL Server jTDS: Falta el archivo ntlmauth.dll requerido para la autenticación integrada de Windows en el directorio JRE que usa el agente Jitterbit en tiempo de ejecución.
    • Usar el controlador SQL Server MS JDBC, o una versión más reciente de Microsoft JDBC Driver for SQL Server: Falta el archivo DLL mssql-jdbc_auth requerido para la autenticación integrada de Windows en los directorios JRE que usa el agente Jitterbit en tiempo de ejecución. Colocar el DLL en el mismo directorio que el archivo JAR de JDBC no es suficiente.
    • La cadena de conexión no incluye los parámetros requeridos para tu controlador.

  • Solución: Elige la opción que corresponda a tu controlador JDBC:

    • SQL Server jTDS:
      1. En el host del agente privado, copia ntlmauth.dll (de la carpeta x64/SSO del paquete de descarga del proyecto jTDS) en <JITTERBIT_HOME>/jre/bin.
      2. En la configuración de la conexión a base de datos, agrega integratedSecurity=true al campo Parámetros de cadena de conexión adicionales.
      3. Reinicia el servicio del agente Jitterbit.
    • SQL Server MS JDBC o una versión más reciente del Controlador JDBC de Microsoft para SQL Server:
      1. En el host del agente privado, copia mssql-jdbc_auth-x.x.x.x64.dll (de la distribución del controlador JDBC, usando la versión que coincida con el archivo JAR de JDBC incluido en tu agente) en <JITTERBIT_HOME>/jre/bin y en <JITTERBIT_HOME>/jre/lib. Haz una copia de seguridad del archivo, ya que puede eliminarse durante actualizaciones mayores del agente.
      2. En la configuración de la conexión a base de datos, agrega integratedSecurity=true;trustServerCertificate=true al campo Parámetros de cadena de conexión adicionales.
      3. Reinicia el servicio del agente Jitterbit.

Autenticación de Windows en SQL Server: Privilegios insuficientes

  • Síntoma: Una conexión de base de datos que utiliza la autenticación de Windows en SQL Server falla aunque las credenciales del dominio parezcan correctas.
  • Causa posible: El usuario de dominio de Windows que ejecuta el servicio del agente Jitterbit carece de los privilegios a nivel de SO requeridos para la seguridad integrada de Windows.
  • Solución:
    1. Otorga al usuario de dominio los privilegios de Windows Iniciar sesión como servicio y Actuar como parte del sistema operativo en el host del agente privado.
    2. Confirma que el usuario de dominio tiene permisos de lectura y escritura en el directorio de instalación del agente Jitterbit.
    3. Reinicia el servicio del agente Jitterbit después de aplicar los cambios de privilegios.

SQL Server: "Cannot insert explicit value for identity column" al insertar en una columna de identidad

  • Síntoma: Una operación del conector de base de datos que escribe en una tabla de SQL Server con una columna de identidad falla con:

    Database Error: Cannot insert explicit value for identity column in table '<table>' when IDENTITY_INSERT is set to OFF.

  • Causa posible: La columna de identidad se incluye en la declaración INSERT que genera el conector de base de datos para el destino. SQL Server rechaza un INSERT que hace referencia a una columna de identidad en su lista de columnas (con un valor explícito o nulo) mientras IDENTITY_INSERT esté configurado en OFF. Mapear el campo a un valor nulo no lo excluye: un campo de destino se omite del INSERT solo cuando se mapea con la función Unmap.

  • Solución:

    • Para permitir que SQL Server asigne el valor de identidad automáticamente, excluye la columna del INSERT mapeando el campo de destino de identidad con la función Unmap. Para excluir la columna solo cuando el origen no proporciona un valor, utiliza un mapeo condicional:

      If($source.id != "", $source.id, Unmap())

      Cuando la condición es falsa, Unmap elimina la columna del INSERT y SQL Server asigna el siguiente valor de identidad. (Proporcionar un valor explícito en la rama verdadera aún requiere que IDENTITY_INSERT esté en ON; consulta la siguiente opción.)

    • Si debes insertar valores explícitos en la columna de identidad, configura IDENTITY_INSERT en la tabla de destino dentro de scripts SQL previos y posteriores en la actividad:

SET IDENTITY_INSERT <table> ON;

SET IDENTITY_INSERT <table> OFF;

Usa esta opción solo cuando intencionalmente desees controlar valores de identidad desde fuera de la base de datos. Permite insertar valores explícitos en la columna de identidad.

SQL Server: La conexión falla con un error de certificado PKIX

  • Síntoma: Una conexión de Base de datos a SQL Server falla con:

    "encrypt" property is set to "true" and "trustServerCertificate" property is set to "false" but the driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption: Error: (certificate_unknown) PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.

    Una conexión que funcionaba anteriormente puede comenzar a fallar después de una actualización del agente a la versión 12.8 o posterior.

  • Posible causa: Las versiones actuales del controlador SQL Server MS JDBC solicitan una conexión cifrada de forma predeterminada y validan el certificado que presenta el servidor de base de datos. La conexión falla cuando ese certificado no puede asociarse a una autoridad de certificación (CA) que el agente ya confía, como un certificado autofirmado, un certificado emitido internamente o el certificado CA de Amazon RDS que presenta una instancia de Amazon RDS para SQL Server. Esta es una falla de confianza de certificado en lugar de cifrado, de modo que una base de datos puede tener cifrado habilitado y un certificado válido instalado y aún así fallar. La versión 12.8 del agente actualizó el controlador incluido a una versión que solicita cifrado de forma predeterminada, por lo que una conexión configurada antes de esa actualización puede fallar después.

  • Resolución: Ingresa encrypt=false; en el campo Parámetros de cadena de conexión adicionales bajo Configuración opcional de la conexión de Base de datos, o inclúyelo en una cadena de conexión manual. Esto funciona en agentes en la nube y privados. Para obtener más información, consulta Cifrado de conexión y certificados de servidor.

    Precaución

    Con encrypt=false, los datos viajan entre el agente y la base de datos sin cifrar. Usa esta opción solo donde sea aceptable para los datos y la ruta de red involucrada.

Conector EDI for Cloud v2

Las entradas de solución de problemas del conector EDI for Cloud v2 se documentan en la guía de solución de problemas de EDI, junto con problemas de EDI de Jitterbit. Las entradas relevantes incluyen:

Conector de correo electrónico

La prueba de conexión de Gmail falla con error de autenticación

  • Síntoma: Una prueba de conexión a una cuenta de Gmail usando autenticación básica falla con un error de autenticación, incluso cuando se ingresa la contraseña correcta de la cuenta de Google.
  • Posible causa: Google requiere una contraseña de aplicación para cuentas con verificación en dos pasos habilitada. La contraseña de la cuenta de Google no es aceptada por SMTP o IMAP cuando la verificación en dos pasos está activa; solo se aceptan contraseñas de aplicación.
  • Resolución:
    1. En tu cuenta de Google, genera una contraseña de aplicación para la aplicación Jitterbit (consulta la página de Google sobre Iniciar sesión con contraseñas de aplicación).
    2. En la configuración de conexión de correo electrónico en Studio, ingresa la contraseña de aplicación en el campo Contraseña SMTP y/o Contraseña IMAP en lugar de la contraseña de la cuenta de Google.

La firma S/MIME falla o es rechazada por proveedores de correo en la nube

  • Síntoma: Los correos configurados con firma S/MIME no se envían, son rechazados por el servidor del destinatario o llegan sin firmar al utilizar un proveedor de correo en la nube como Microsoft 365 o Exchange Online.
  • Posibles causas:
    • Los proveedores en la nube requieren un certificado S/MIME emitido por una autoridad certificadora (AC) confiable. Los certificados autofirmados no son aceptados por proveedores en la nube como Microsoft 365 (Exchange Online).
    • S/MIME funciona solo cuando se utilizan agentes privados. Si la operación se ejecuta en un agente en la nube, la firma S/MIME no se aplica independientemente del tipo de certificado.
  • Resolución:
    1. Obtener un certificado S/MIME de una AC confiable. Let's Encrypt proporciona certificados gratuitos aceptados por los principales proveedores en la nube.
    2. Reemplazar el certificado autofirmado en la actividad Email Enviar correo con el certificado emitido por la AC (consultar Requisitos previos para cifrado S/MIME).
    3. Para agentes privados, confirmar que el certificado se importó correctamente en el almacén de confianza predeterminado del agente. Para agentes en la nube, la firma S/MIME no es compatible.

La conexión de correo de Microsoft 365 con autenticación ROPC falla cuando MFA está habilitado

  • Síntoma: Una conexión OAuth 2.0 de Microsoft 365 que utiliza la concesión de Credenciales del Propietario del Recurso (ROPC) no se autentica, incluso cuando el nombre de usuario, contraseña, ID de cliente, ID de inquilino y secreto de cliente son todos correctos.
  • Posible causa: La autenticación ROPC requiere que la autenticación multifactor (MFA) esté deshabilitada para las credenciales de Microsoft 365 utilizadas con el conector. La concesión ROPC no puede satisfacer un desafío MFA, por lo que la solicitud de token falla cuando una política MFA se aplica a la cuenta.
  • Resolución:
    • Utilizar una cuenta de Microsoft 365 cuyas credenciales no estén sujetas a una política MFA. Para mantener la seguridad, crear un inquilino o directorio dedicado de Microsoft Entra ID que no implemente MFA, como se describe en Requisitos previos para Microsoft 365.
    • Si no es posible eliminar MFA de la cuenta, utilizar un método de autenticación compatible diferente para la conexión en lugar de ROPC.

Enviar correo falla cuando la misma dirección aparece en varios campos de destinatario

  • Síntoma: Una actividad Enviar correo de Correo falla en tiempo de ejecución cuando la misma dirección de correo está presente en más de uno de los campos Para, CC o BCC.
  • Posible causa: El conector de Correo no permite que la misma dirección aparezca en varios campos de destinatario en una única solicitud de envío. Esto se aplica a las direcciones configuradas directamente en la actividad y a las direcciones suministradas dinámicamente a través de una asignación de transformación.
  • Resolución:
    • Revisar los campos Para, CC y BCC en la configuración de la actividad y en cualquier asignación de transformación para la actividad a fin de confirmar que ninguna dirección aparece en más de un campo.
    • Si las listas de destinatarios se ensamblan dinámicamente utilizando variables o scripts, agregar una verificación de deduplicación antes de pasar las direcciones a la actividad.

Conectores Epicor

Epicor Prophet 21: La operación falla en tiempo de ejecución con múltiples condiciones de filtro

  • Síntoma: Una actividad Query de Epicor Prophet 21 falla en tiempo de ejecución cuando la Cadena de filtro contiene más de una condición de filtro, aunque la actividad parezca válida en Studio.
  • Posible causa: Una limitación en la API de Middleware de Epicor Prophet 21 impide que se procesen múltiples condiciones de filtro. La operación parece válida en Studio pero falla en tiempo de ejecución cuando hay más de un filtro presente.
  • Resolución:
    • Reduce la Cadena de filtro a una sola condición de filtro.
    • Si se necesitan múltiples condiciones de filtro, recupera un conjunto de resultados más amplio usando un filtro único y aplica el filtrado adicional en un paso de transformación o secuencia de comandos después de la actividad.

Conectores de archivo

FTP, Recurso compartido de archivos y Almacenamiento local: "Ningún archivo coincide con el filtro de archivo" en pasos de archivo o seguimiento

  • Síntoma: Una actividad de lectura de FTP, Recurso compartido de archivos o Almacenamiento local falla porque el archivo que espera leer ya no se encuentra en la ruta de origen:

    Failed to read file from the source "Read". Reason: No files match the file filter "<filter>".

    La actividad que procesó anteriormente el archivo se completó correctamente; la falla ocurre en un paso posterior (a menudo un paso de archivo o notificación) que intenta leer el mismo archivo con el mismo filtro.

  • Posibles causas:

    • La actividad de procesamiento ya movió o eliminó el archivo de origen como parte de su comportamiento Después del procesamiento, por lo que el paso de archivo no tiene nada que hacer coincidir.
    • Se lanza una operación secundaria de forma asíncrona y la operación principal intenta leer el archivo de salida de la operación secundaria antes de que esta haya terminado de escribirlo.
    • Una actividad Escritura de FTP con Usar cambio de nombre de FTP habilitado (predeterminado) escribe el archivo con un nombre temporal y lo renombra al nombre final al completarse. Una operación de lectura descendente que se ejecuta antes de que se complete el cambio de nombre no encontrará el archivo.
  • Resolución:
    • Confirma si el paso anterior ya manejó el archivado a través de sus opciones integradas Después del procesamiento (mover, renombrar, eliminar). Si es así, un paso de archivo por separado es redundante y debe eliminarse.
    • Si se requiere un paso de archivo por separado, rediseña la cadena para que el procesamiento y el archivado ocurran contra la misma referencia de archivo en memoria en lugar de releer desde el origen. Por ejemplo, pasa el contenido leído a través de Almacenamiento temporal al paso de archivo en lugar de releer la ruta de origen.
    • Si un paso posterior lee la salida producida por una operación secundaria, ejecuta la operación secundaria de forma síncrona para que su salida exista antes de la lectura. Establece el Tipo de ejecución de la herramienta Invocar operación en De forma síncrona, o, cuando llames a la operación desde un script, ejecuta RunOperation de forma síncrona (predeterminado). Insertar un retraso fijo (por ejemplo, con la función Sleep) añade latencia y no garantiza que el archivo esté listo.
    • Si una actividad Escritura de FTP está escribiendo en la misma ubicación, verifica si Usar cambio de nombre de FTP está habilitado en la actividad Escritura de FTP. Si la lectura descendente se ejecuta antes de que se complete el cambio de nombre, deshabilita Usar cambio de nombre de FTP en la actividad de escritura o asegúrate de que la operación de lectura no se ejecute hasta que la operación de escritura se haya completado totalmente.

FTP, File Share y Local Storage: Carpeta de errores no escrita en caso de fallo de conexión

  • Síntoma: Después de que falla una actividad de FTP, File Share o Local Storage, no aparece ningún archivo en la carpeta de errores configurada.
  • Posible causa: La carpeta de errores está diseñada para archivar una copia del archivo de origen después del procesamiento sin éxito, por lo que captura archivos solo cuando la actividad se ejecuta y luego falla (por ejemplo, un error de permiso de escritura en el servidor). Si no se puede establecer la conexión al servidor en absoluto, la operación falla antes de que la actividad lea algún archivo, por lo que no hay archivo que escribir en la carpeta de errores.
  • Resolución:
    • Si la carpeta de errores está vacía después de un fallo, consulta los registros de operaciones para identificar un error a nivel de conexión (como un fallo de autenticación o un mensaje de host no alcanzable).
    • Usa el botón Test en la conexión para confirmar si el problema está a nivel de red o autenticación.

FTP, File Share y Local Storage: Palabras clave del nombre de archivo no resueltas en rutas de carpetas de éxito y error

  • Síntoma: Las operaciones mueven archivos a carpetas de éxito o error después del procesamiento, pero la ruta de destino incluye texto de palabras clave sin expandir en lugar de valores resueltos. Es posible que la operación falle o que los archivos se escriban en ubicaciones inesperadas.
  • Posibles causas:
    • Los campos de ruta de la carpeta de éxito y carpeta de error en actividades de FTP, File Share y Local Storage no admiten sustitución de palabras clave de nombre de archivo. Las variables no se expanden en estos campos.
    • Estos campos hacen referencia a directorios en la máquina del agente privado, no en el servidor remoto. Las rutas relativas se interpretan en relación con el sistema de archivos del host del agente.
  • Resolución:
    • Usa solo rutas literales (sin variables de palabras clave de nombre de archivo) para los campos de carpeta de éxito y error.
    • Si se requieren rutas dinámicas, añade un paso de script después de la actividad para mover o renombrar el archivo procesado a la ubicación prevista utilizando funciones de archivo.

FTP, File Share, Local Storage y Temporary Storage: Escribir encabezados no produce un archivo solo de encabezados cuando el origen no devuelve registros

  • Síntoma: Una actividad de escritura basada en archivos con la opción Write Headers habilitada (FTP Write, File Share Write, Local Storage Write o Temporary Storage Write) no escribe encabezados cuando el origen no devuelve registros. Se crea un archivo vacío o no se crea ningún archivo (si también se selecciona Do not create empty files).
  • Causa: Este es el comportamiento esperado. Los encabezados se escriben como parte de la salida de la transformación, y la transformación se ejecuta solo cuando el origen devuelve al menos un registro. Cuando el origen no devuelve registros, la transformación se omite, por lo que no se escribe ninguna salida (incluidos los encabezados), y Studio registra una advertencia indicando que el origen está vacío. Esto no es específico de un conector de origen particular o destino de archivo plano.

FTP: La operación falla después de muchos inicios de sesión rápidos en el mismo servidor

  • Síntoma: Una operación que usa el conector FTP (sobre el protocolo FTP o SFTP) que se autentica en el mismo servidor muchas veces en rápida sucesión (por ejemplo, leyendo cientos de archivos pequeños dentro de un bucle, u muchas operaciones ejecutándose contra el mismo servidor en una programación) eventualmente falla con una negación de inicio de sesión o un error de conexión. La misma operación funciona correctamente bajo una carga menor.
  • Posibles causas:
    • El conector FTP abre y autentica una nueva conexión para cada ejecución de actividad y la cierra cuando la operación termina; no se reutiliza una sesión entre actividades, entre ejecuciones de operaciones o entre proyectos. Esto es por diseño. Cuando muchas operaciones se ejecutan contra el mismo servidor, por ejemplo varias operaciones programadas o múltiples proyectos dirigidos al mismo host, cada ejecución se autentica de forma independiente.
    • El servidor remoto está configurado con un número máximo de conexiones, autenticaciones por minuto o sesiones concurrentes por usuario, y la tasa de inicio de sesión combinada de Jitterbit excede ese límite.
  • Resolución:
    • Cuando sea posible, rediseña la operación para hacer menos conexiones. Reemplaza una actividad Read dentro de un bucle con una única actividad Read que usa un comodín en el campo Get Files (por ejemplo, *.xml o data_*.csv), luego divide los datos recuperados en registros individuales dentro de una transformación.
    • Si la operación debe procesar archivos uno a la vez, solicita al administrador del servidor FTP que aumente el límite por usuario en conexiones concurrentes o autenticaciones por minuto.

SFTP "Inicio de sesión denegado. Falló la autenticación." al usar claves SSH

  • Síntoma: Una operación SFTP usando autenticación de clave privada SSH falla con Login denied. Authentication failure., aunque las mismas claves se autentican exitosamente desde un cliente SFTP interactivo.

    Failed to get ftp directory list for url sftp://example.com:22/. Login denied. Authentication failure.

  • Posibles causas:

    • La clave privada está protegida por una contraseña, pero falta la configuración PrivateKeyPassphrase en la sección [SSH] del jitterbit.conf del agente.
    • Se configura una contraseña en el punto de conexión FTP junto con la clave privada. La presencia de una contraseña en la configuración del punto de conexión interfiere con la autenticación basada en clave.

  • Resolución:

    • Para agentes privados, confirma que la sección [SSH] de jitterbit.conf contiene la ruta PrivateKeyFile correcta y, si la clave está protegida por contraseña, el valor PrivateKeyPassphrase correspondiente (consulta Conectarse a SFTP con claves SSH).
    • En la configuración del punto de conexión FTP, limpia el campo Password cuando la autenticación es por clave SSH.
    • Confirma que la clave está en un formato que soporta el agente (OpenSSH). Convierte la clave con ssh-keygen si está en formato PuTTY (.ppk) u otro formato que no sea OpenSSH.

FTP Write: "Use FTP Rename" falla al escribir en un servidor SFTP

  • Síntoma: Una actividad FTP Write configurada con la opción Use FTP Rename falla cuando el destino es un servidor SFTP, con un error similar a:

    Failed to put ... to the url ...
Quote command returned error. Rename command failed: <reason>.

    El <reason> es típicamente No such file or directory, o Permission denied para un archivo cuyo nombre contiene caracteres multibyte.

  • Posibles causas:

    • En agentes anteriores al 11.56, la opción Use FTP Rename no respetaba de forma confiable el paso de renombrado al escribir en un servidor SFTP, particularmente en operaciones de patrón de archivo.

  • El nombre de archivo contiene caracteres multibyte y el servidor SFTP no admite renombrar archivos con nombres que los contengan. A partir de la versión 12.8 del agente, el conector FTP puede leer y escribir archivos con nombres multibyte; sin embargo, con Use FTP Rename el agente carga el archivo bajo un nombre temporal (sufijo -jbupload) y luego lo renombra al nombre final. Si el servidor no puede renombrar el nombre multibyte, devuelve un Permission denied engañoso. Los nombres de archivo que solo utilizan caracteres ASCII no se ven afectados. Esta es una limitación del servidor SFTP, no de Jitterbit.

  • Resolución:

    • Verifica que el agente sea versión 11.56 o posterior, donde Use FTP Rename con SFTP funciona como se esperaba. Los agentes en la nube se actualizan automáticamente; actualiza los agentes privados si es necesario.

    • Desactiva la casilla Use FTP Rename en la configuración de la actividad para que el agente escriba directamente en la ruta de destino en lugar de cargar con un nombre temporal y renombrar. Esto evita el paso de renombrado y resuelve ambas causas.

    • Para el caso multibyte, usa alternativamente un servidor SFTP que admita renombrar archivos con nombres que contengan caracteres multibyte.

SFTP: No se admite agregar al archivo

  • Síntoma: Una actividad Write de FTP configurada con la opción Append To File no agrega al archivo existente cuando el destino es un servidor SFTP.
  • Causa posible: El protocolo SFTP no admite agregar a archivos existentes. Esta es una limitación a nivel de protocolo, no un problema de configuración de Jitterbit.
  • Resolución:
    • Usa FTP o FTPS si se requiere el comportamiento de agregar.
    • Si se requiere SFTP, implementa la lógica de agregar manualmente: lee el contenido del archivo existente, combínalo con los datos nuevos y escribe el resultado completo como un archivo completo.

FTP: Los nombres de archivo que contienen # no se manejan correctamente

  • Síntoma: Una actividad del conector FTP (sobre el protocolo FTP o SFTP) falla cuando el nombre del archivo de origen o destino contiene un carácter hash (#). Leer el archivo devuelve un error como No File with that name o Error in SSH Layer, y escribir el archivo produce un nombre de archivo truncado.
  • Causa posible: El conector FTP trata la ruta del archivo como una URL, en la que el carácter hash es un delimitador de fragmento reservado. El conector analiza la parte de la ruta antes del # y descarta el resto.
  • Resolución:
    • Renombra los archivos para eliminar o reemplazar el carácter # antes de que Jitterbit los lea o escriba.
    • Para que el conector codifique en URL los nombres que contienen caracteres especiales como #, establece jitterbit.source.ftp.encode_url en true en un script de transformación para nombres de archivo o carpeta de origen, y jitterbit.target.ftp.encode_url en true para archivos escritos en el destino.

File Share: Las rutas UNC con nombres de servidor fallan en agentes en la nube

  • Síntoma: Las conexiones de File Share que utilizan rutas UNC (por ejemplo, \\server\share) fallan al conectarse cuando la operación se ejecuta en un agente en la nube.
  • Causa posible: Los agentes en la nube pueden resolver rutas UNC usando una dirección IP pública, pero no pueden resolver nombres de host del servidor en rutas UNC.
  • Resolución:
    • Reemplaza el nombre del servidor en la ruta UNC con la dirección IP pública del servidor (por ejemplo, \\192.0.2.1\share).
    • Si se requiere la resolución de nombres de servidor en rutas UNC, usa un agente privado en su lugar.

File Share: Los archivos más grandes de 2 GB pueden fallar al recuperarse

  • Síntoma: Una actividad Read de File Share puede fallar al recuperar archivos individuales más grandes de 2 GB. Los archivos más pequeños se recuperan sin problema.
  • Causa posible: El conector File Share tiene una limitación conocida con archivos individuales más grandes de 2 GB.
  • Resolución: No existe una opción de configuración que elimine este límite. Como solución alternativa, divide el archivo en segmentos más pequeños en la fuente para que cada archivo sea menor de 2 GB antes de que la actividad Read de File Share lo recupere.

Local Storage: No disponible en agentes en la nube

  • Síntoma: Una operación que utiliza un conector Local Storage falla cuando se ejecuta en un agente en la nube.
  • Causa posible: Local Storage accede al sistema de archivos de la máquina donde está instalado el agente. Los agentes en la nube se ejecutan en un entorno alojado y no exponen un sistema de archivos local para este propósito.
  • Resolución:
    • Utiliza agentes privados para cualquier operación que requiera el conector Local Storage. Local Storage está deshabilitado en agentes privados de forma predeterminada, así que también habilítalo en el archivo de configuración del agente privado (consulta Enable local file location).
    • Para flujos de trabajo de agentes en la nube, reemplaza Local Storage con Temporary Storage o un conector de almacenamiento externo (File Share, FTP o Cloud Datastore).

Temporary Storage: Archivos desaparecidos cuando los lee una operación posterior

  • Síntoma: Los archivos de Temporary Storage escritos por una operación desaparecen cuando una operación posterior intenta leerlos.
  • Causas posibles:
    • El servicio de limpieza de Harmony elimina archivos de Temporary Storage después de 24 horas de forma predeterminada.
    • Cada agente en un grupo de agentes tiene su propio Temporary Storage local. Se garantiza que las operaciones en la misma cadena de operaciones se ejecuten en el mismo agente, pero una operación posterior que no esté en la misma cadena puede distribuirse a un agente diferente y acceder a una instancia de Temporary Storage diferente, por lo que no encuentra el archivo, independientemente de la ventana de 24 horas. Consulta Important notes.
  • Resolución:
    • Vincula las operaciones que deben compartir archivos de Temporary Storage en la misma cadena de operaciones utilizando acciones de operación, donde el comportamiento de Temporary Storage es consistente y confiable.
    • Para agentes privados, la frecuencia de limpieza puede ajustarse en la sección [FileCleanup] de jitterbit.conf. Consulta [FileCleanup].
    • Si los archivos no pueden consumirse dentro de la misma cadena o deben persistir más de 24 horas, utiliza un conector de almacenamiento persistente accesible a todos los agentes (como File Share, FTP o Cloud Datastore) en lugar de Temporary Storage.

Temporary Storage: Caracteres restringidos en rutas de archivo

  • Síntoma: Una actividad de Read o Write de Temporary Storage falla cuando la ruta del archivo contiene ciertos caracteres especiales.
  • Causa posible: Los siguientes caracteres no se admiten en rutas de archivo de Temporary Storage: ~, %, $, ", <, >, :, ?
  • Resolución:
    • Elimina o reemplaza los caracteres no admitidos en la ruta del archivo. Los siguientes caracteres se admiten: !, @, #, ^, &, *, (, ), [, ], ', ;
    • Tanto / como \ se aceptan como separadores de ruta.

Almacenamiento temporal: límite de tamaño de archivo de 50 GB en agentes en la nube

  • Síntoma: Una actividad de Almacenamiento temporal Escribir falla al escribir archivos grandes a través de un agente en la nube.
  • Causa posible: Los agentes en la nube imponen un tamaño máximo de archivo de 50 GB por archivo para Almacenamiento temporal.
  • Resolución:
    • Utiliza un agente privado para flujos de trabajo que necesiten escribir archivos individuales mayores de 50 GB en Almacenamiento temporal.
    • Si solo están disponibles agentes en la nube, divide los conjuntos de datos grandes en múltiples archivos menores de 50 GB antes de escribir en Almacenamiento temporal.

Conector HTTP

HTTP v2: el encabezado de autorización duplicado causa 400 Bad Request

  • Síntoma: Las operaciones del conector HTTP v2 fallan con un error 400 cuando se configuran tanto la autenticación a nivel de conexión como un encabezado de solicitud Authorization definido manualmente en la misma conexión o actividad.
  • Causa posible: Cuando se configura la autenticación en una conexión HTTP v2 (por ejemplo, Basic u OAuth), el conector agrega automáticamente un encabezado Authorization a cada solicitud. Agregar un segundo encabezado Authorization manualmente resulta en dos encabezados conflictivos, que la mayoría de los servidores rechaza con un error 400.
  • Resolución:
    • Elimina cualquier encabezado Authorization agregado manualmente de los encabezados de solicitud en la configuración de la actividad o conexión.
    • Usa solo la configuración de autenticación integrada en la conexión para manejar la autorización. No agregues un encabezado Authorization manual junto con la autenticación configurada.
    • Si necesitas establecer el encabezado Authorization dinámicamente a nivel de actividad, establece el tipo de autenticación de la conexión en Sin autenticación y configura el encabezado de solicitud Authorization de la actividad según sea necesario.

HTTP v2: el valor JSON en una variable de proyecto de encabezado de solicitud no se puede analizar

  • Síntoma: Una actividad de HTTP v2 que lee un valor de encabezado de solicitud de una variable de proyecto que contiene una cadena JSON falla con un error de análisis:

    Expected a ',' or ']' at 139 [character 140 line 1]

    El mismo JSON funciona cuando se pega directamente en la columna Valor de la tabla Encabezados de solicitud.

  • Causa posible: Cuando se lee un valor de encabezado de solicitud de una variable de proyecto, el conector HTTP v2 no escapa las comillas incrustadas de la manera que lo hace cuando escribes el valor directamente en la tabla Encabezados de solicitud. Las comillas sin escape rompen la cadena de encabezado antes de que llegue al destino.

  • Resolución:
    • Al almacenar JSON en una variable de proyecto que se usará como valor de encabezado, escapa cada comilla doble con una barra invertida. Por ejemplo, almacena el valor como {\"success\": \"true\"} en lugar de {"success": "true"}.
    • Si el contenido JSON es estático, pégalo directamente en la columna Valor de la tabla Encabezados de solicitud en lugar de usar una variable. El conector aplica el escape necesario en esa ruta.

HTTP e HTTP v2: la URL contiene múltiples caracteres ?

  • Síntoma: Una operación HTTP o HTTP v2 falla en el sistema destino. Los registros del agente muestran que la URL de la solicitud contiene más de un ? entre segmentos, por ejemplo https://api.example.com/endpoint?param1=A?param2=B.
  • Causa posible: Los parámetros de consulta se declararon en dos lugares: anexados directamente a la ruta de la URL y también agregados a la tabla Request Parameters (Parámetros de solicitud) de la actividad. El conector concatena ambos conjuntos e inserta un segundo ? en lugar de un &.
  • Resolución:
    • Elimina cualquier segmento de cadena de consulta de la ruta de la URL. La URL base debe contener solo la ruta misma (por ejemplo, https://api.example.com/endpoint).
    • Define cada parámetro de consulta en la tabla Request Parameters (Parámetros de solicitud) de la actividad. El conector inserta los caracteres ? y & automáticamente al construir la URL final.

HTTP v2: Codificación de URL doble cuando "Encode request URL" está habilitado

  • Síntoma: Las llamadas a la API REST realizadas a través del conector HTTP v2 fallan en el sistema destino porque los parámetros de URL aparecen con doble codificación en la solicitud saliente (por ejemplo, un espacio %20 se convierte en %2520).
  • Causa posible: Cuando Encode request URL (Codificar URL de solicitud) está habilitado en la configuración de conexión HTTP v2, el conector codifica la URL completa antes de enviarla. Si los parámetros de URL ya contienen caracteres codificados en porcentaje, esos caracteres se codifican una segunda vez.
  • Resolución:
    • Deshabilita Encode request URL (Codificar URL de solicitud) en la configuración de conexión HTTP v2 cuando la URL o los parámetros ya estén codificados o construidos usando la función URLEncode.
    • Si Encode request URL (Codificar URL de solicitud) debe permanecer habilitado, asegúrate de que los parámetros pasados a la URL no estén pre-codificados antes de llegar a la conexión.

HTTP v2: La operación falla cuando Base URL redirige

  • Síntoma: Una operación HTTP v2 falla inmediatamente cuando la Base URL configurada devuelve una respuesta de redirección (3xx).
  • Causa posible: Follow redirects (Seguir redirecciones) está deshabilitado en la configuración de conexión HTTP v2, por lo que las respuestas de redirección se tratan como errores en lugar de seguirse automáticamente.
  • Resolución: En la configuración de conexión HTTP v2, habilita Follow redirects (Seguir redirecciones) para permitir que el conector siga automáticamente las respuestas de redirección a la URL destino final.

HTTP v2: Las variables en la ruta de la actividad no se resuelven

  • Síntoma: Una actividad HTTP v2 usa una variable global, de proyecto o de Jitterbit en su campo Path (Ruta), pero en tiempo de ejecución la variable se envía literalmente (sin resolver) en lugar de reemplazarse con su valor.
  • Causa posible: Se ingresó una URL completa (una que incluye el protocolo y el host, como https://api.example.com/...) en el campo Path (Ruta). Las variables no se admiten en URLs completas. Solo se resuelven en una ruta parcial que se anexa a la Base URL de la conexión.
  • Resolución:
    1. En la conexión HTTP v2, establece Base URL (URL base) en la porción de protocolo y host del punto de conexión (por ejemplo, https://api.example.com).
    2. En el campo Path (Ruta) de la actividad, ingresa solo la ruta parcial que sigue a la URL base, y coloca la variable dentro de esa ruta parcial (por ejemplo, /records/[recordId]). El conector resuelve la variable y anexa el resultado a Base URL (URL base) en tiempo de ejecución.

HTTP v2: código de estado de respuesta no disponible en variables de Jitterbit

  • Síntoma: Los scripts que leen variables de origen o destino de Jitterbit para capturar el código de estado de respuesta HTTP después de ejecutar una actividad HTTP v2 no reciben valor. El mismo enfoque funciona con el conector HTTP, pero no con HTTP v2.
  • Posible causa: El conector HTTP v2 no rellena las variables de origen o destino de Jitterbit. Los datos de respuesta, incluido el código de estado HTTP, se devuelven a través del esquema de respuesta de la actividad en su lugar.
  • Resolución:
    • Para capturar el código de estado usando el esquema de respuesta predeterminado, asigna el campo statusCode, que se encuentra bajo el nodo responseItem/error de la respuesta y contiene el código de estado HTTP (por ejemplo, 200, 403). Para obtener detalles sobre la estructura del esquema de respuesta, consulta la documentación de configuración de actividad para cualquier actividad HTTP v2.
    • Para capturar el código de estado al usar un esquema de respuesta personalizado, habilita Include Additional Properties from HTTP Response in the Schema en la configuración de la actividad. Esto envuelve el esquema con una estructura definida por Jitterbit que incluye __jitterbit_api_statuscode__ (el código de estado) y __jitterbit_api_errorbody__ (el cuerpo de respuesta para solicitudes sin éxito).
    • Para que el código de estado esté disponible cuando la API devuelve una respuesta sin éxito, habilita Ignore operation error in case of non-successful status code en la configuración opcional de la actividad. Sin este parámetro, la operación falla en respuestas sin éxito antes de que los datos de respuesta se puedan asignar.

HTTP v2: espacios de nombres XML reescritos al usar un esquema de solicitud personalizado

  • Síntoma: Una operación HTTP v2 que envía una carga de trabajo XML a un servicio web SOAP o XML falla con un error del servidor (como 500 Internal Server Error) aunque la misma carga de trabajo funciona cuando se envía desde Postman o SoapUI. Al inspeccionar el cuerpo de la solicitud recibida por el destino, se muestra que las declaraciones de espacio de nombres XML se han consolidado en el elemento raíz y los prefijos de espacio de nombres originales se han reemplazado con genéricos (por ejemplo, soapenv:Envelope se convierte en Envelope xmlns="...", y los prefijos de elemento se renumeran como ns, ns1, ns2).
  • Posible causa: Cuando se utiliza un esquema de solicitud personalizado en la configuración de la actividad HTTP v2, la transformación normaliza el XML de forma predeterminada, moviendo todas las declaraciones de espacio de nombres al nodo raíz y reasignando sus prefijos. Los servicios SOAP y otros puntos finales XML que validan la coherencia del prefijo de espacio de nombres rechazan la carga de trabajo modificada.

  • Resolución:

    • En la versión del agente 12.8 o posterior, establece jitterbit.target.xml.preserve.namespace.prefix en true en un paso de script anterior a la transformación, para mantener los prefijos de espacio de nombres del XML de origen en lugar de reasignar genéricos:

      $jitterbit.target.xml.preserve.namespace.prefix = true;

    • Si tus agentes privados son anteriores a 12.8, o el destino también rechaza la consolidación de declaraciones de espacio de nombres en el elemento raíz, utiliza el esquema de solicitud predeterminado en lugar de uno personalizado y asigna la carga de trabajo XML completa como cadena en el campo body del esquema. La carga de trabajo se trata entonces como cadena en lugar de XML analizado, por lo que sus declaraciones de espacio de nombres se conservan. El esquema de respuesta puede seguir siendo un esquema personalizado.

HTTP v2: Espacios codificados como + en lugar de %20

  • Síntoma: Las llamadas de la API REST que utilizan el conector HTTP v2 fallan en el sistema de destino porque los espacios en la URL se codifican como + en lugar de %20, lo que causa que el destino devuelva un error de recurso no encontrado.
  • Solución:
    • En la conexión HTTP v2, activa la opción Encode request URL. El conector entonces codifica la URL de solicitud, codificando los espacios como %20.
    • Proporciona la URL de solicitud completamente sin codificar. No pre-codifiques caracteres ni apliques la función URLEncode a la URL, porque los caracteres ya codificados se codifican dos veces cuando Encode request URL está activado (por ejemplo, example+string%20value se convierte en example%20string%2520value).

HTTP: Envía null como la cadena "null"

  • Síntoma: Una actividad HTTP POST o PUT envía campos asignados con la función Null como la cadena "null" (u los omite) en lugar de emitir un literal JSON null. Esto ocurre cuando el esquema de solicitud se define en la actividad.
  • Posible causa: Cuando el esquema de solicitud se define en la actividad HTTP, el conector no serializa un Null asignado como un JSON null. Cuando el esquema se define en la transformación en su lugar, sin ningún esquema de solicitud proporcionado en la actividad, el conector envía un Null asignado como un JSON null correctamente.
  • Solución:
    • Migra la actividad al conector HTTP v2, que serializa Null correctamente. Jitterbit recomienda convertir las conexiones y actividades HTTP existentes a HTTP v2.
    • Si la actividad debe permanecer en HTTP, define el esquema de solicitud en la transformación en lugar de en la actividad y deja el esquema de solicitud de la actividad sin establecer. Con el esquema definido en la transformación, el conector serializa un Null asignado a un JSON null correctamente.

Conector LDAP

La actividad LDAP Delete Entry falla cuando la entrada de destino tiene entradas secundarias

  • Síntoma: Una actividad LDAP Delete Entry falla con un error del servidor LDAP (por ejemplo, notAllowedOnNonLeaf o un mensaje que indica que la entrada no es un nodo hoja).
  • Posible causa: El protocolo LDAP no permite eliminar una entrada que tiene entradas secundarias (subordinadas). La entrada debe ser un nodo hoja sin hijos para que la eliminación sea exitosa.
  • Solución:
    • Antes de eliminar la entrada principal, elimina primero todas las entradas secundarias. Recorre la jerarquía desde las entradas más profundas hacia arriba.
    • Si se requiere eliminar un subárbol completo, implementa un script que identifique y elimine entradas desde la parte inferior del árbol hacia arriba, usando RunOperation con la actividad LDAP Delete Entry para cada entrada.

LDAP Search Entry: La expresión de filtro distingue mayúsculas y minúsculas en algunos servidores

  • Síntoma: Una actividad LDAP Search Entry no devuelve resultados o devuelve un error, aunque las entradas consultadas existan en el directorio.
  • Posible causa: Algunos servidores LDAP requieren que los nombres de atributos en las expresiones de filtro coincidan exactamente con la capitalización utilizada por el esquema del servidor. La expresión de filtro pre-rellenada por Studio utiliza la capitalización de título para la clase estructural (por ejemplo, ObjectClass), pero algunos servidores requieren una capitalización diferente (por ejemplo, objectClass).
  • Solución:
    1. En la configuración de la actividad LDAP Search Entry, revisa el campo Filter Expression pre-rellenado.
    2. Ajusta la capitalización de los nombres de atributos para que coincida con lo que espera el servidor LDAP de destino. Por ejemplo, cambia ObjectClass a objectClass si el servidor requiere minúsculas.
    3. Consulta la documentación o definición del esquema de tu servidor LDAP para conocer las convenciones requeridas de nomenclatura de atributos.

Conectores de Microsoft

Microsoft SharePoint Online: Las conexiones de esquema SOAP fallan después de la retirada de IDCRL

  • Síntoma: Las operaciones que usan un conector Microsoft SharePoint Server con el tipo de conexión de esquema SOAP han comenzado a fallar o devuelven errores de autenticación al conectarse a SharePoint Online.
  • Causa posible: Microsoft retiró el método IDCRL (Identity Client Runtime Library) que utilizan las conexiones de esquema SOAP para SharePoint Online. Después del 1 de mayo de 2026, se espera que las operaciones que usan el esquema SOAP de SharePoint para conexiones de SharePoint Online fallen.
  • Resolución:
    1. En Studio, abre cada conexión de SharePoint afectada y cambia la configuración de Esquema de SOAP a REST.
    2. Reconfigura cualquier actividad que utilizara el esquema SOAP para usar operaciones REST equivalentes.
    3. Prueba e implementa nuevamente las operaciones afectadas.
    4. Para detalles de migración, consulta la documentación del conector Microsoft SharePoint Server.

Microsoft Dynamics 365 Business Central v2: Los nombres de tipo no son compatibles con los metadatos

  • Síntoma: Las operaciones que usan el conector Microsoft Dynamics 365 Business Central v2 fallan con errores que indican que los nombres de tipo en la carga útil no son compatibles con los metadatos de OData.
  • Causa posible: Ciertos extremos de API de OData de Dynamics 365 Business Central requieren anotaciones de tipo de OData en la carga útil de la solicitud. De manera predeterminada, el conector no incluye estas anotaciones, lo que causa errores de incompatibilidad de tipo en esos extremos.
  • Resolución:
    1. Abre la configuración de la actividad Actualizar de Microsoft Dynamics 365 Business Central v2.
    2. En Configuración opcional, habilita Establecer tipo de OData en carga útil.
    3. Guarda la actividad y vuelve a probar las operaciones afectadas.

Microsoft Entra ID: Los atributos de extensión no se pueden seleccionar como condiciones de filtro de consulta

  • Síntoma: Al configurar una actividad Consultar de Microsoft Entra ID, el campo onPremisesExtensionAttributes y sus campos de atributo de extensión secundarios (por ejemplo, extensionAttribute1 a través de extensionAttribute15) no aparecen en el selector de Campos de objeto en el paso 3 y no se pueden seleccionar como condiciones de filtro de cláusula condicional.
  • Causa posible: onPremisesExtensionAttributes es un objeto de tipo complejo (anidado). El selector de Campos de objeto del paso 3 expone solo campos de tipo de datos primitivos; los campos de tipo complejo se excluyen de la lista de selección.
  • Resolución: Los campos onPremisesExtensionAttributes no necesitan seleccionarse en el paso 3 para que se devuelvan. Aparecen en el esquema de salida de la actividad en el paso 4 y se rellenan en tiempo de ejecución cuando se ejecuta la operación. Para acceder a los valores de atributos de extensión, asigna desde onPremisesExtensionAttributes y sus campos secundarios en la transformación.

Actividad Microsoft Entra ID Update: Los campos DateTime se rechazan con discrepancia de tipo Edm.String

  • Síntoma: Una actividad Actualizar de Microsoft Entra ID falla con:
Se encontró un valor que tiene un nombre de tipo incompatible con los metadatos.
El valor especificó su tipo como 'Edm.String', pero el tipo especificado en los metadatos es 'Edm.DateTimeOffset'.
[HTTP/1.1 400 Bad Request]
  • Causa posible: El conector envía valores de campos DateTime (como employeeHireDate) sin la anotación @odata.type requerida por la API de Microsoft Graph. Sin la anotación, el valor se interpreta como Edm.String en lugar de Edm.DateTimeOffset, lo que causa un error 400.
  • Resolución:
    1. Abre la configuración de la actividad Actualizar de Microsoft Entra ID.
    2. En el paso 1, expande Configuración opcional y habilita Establecer tipo OData en carga útil.
    3. Guarda la actividad, vuelve a implementarla y ejecuta nuevamente la operación.

Consulta de Microsoft Entra ID: "Unsupported or invalid query filter clause" en propiedades filtradas

  • Síntoma: Una actividad Consultar de Microsoft Entra ID falla cuando se aplica una condición de filtro en el paso 3:

    (Request_UnsupportedQuery) Unsupported or invalid query filter clause specified for property '<property>' of resource '<object>'. [HTTP/1.1 400 Bad Request]

    La misma consulta se ejecuta correctamente cuando no se aplica ningún filtro.

  • Causa posible: El filtrado en ciertas propiedades de Microsoft Entra ID (como companyName y createdDateTime) utiliza la capacidad de consulta avanzada de la API de Microsoft Graph, que requiere $count=true en la cadena de consulta. Sin ella, la API rechaza el filtro incluso cuando la sintaxis es correcta. El conector incluye automáticamente el encabezado ConsistencyLevel: eventual requerido, pero $count=true debe agregarse por separado.

  • Resolución: Elige una de las siguientes opciones según la pestaña utilizada en el paso 3:
    • Pestaña Básico: Selecciona la casilla Incluir Recuento. Esto agrega $count=true a la consulta automáticamente.

    • Pestaña Avanzado: Añade &$count=true manualmente a la cadena de filtro. Por ejemplo:

      $filter=companyName eq 'Example Corp'&$count=true

Para la lista de propiedades que requieren sintaxis de consulta avanzada, consulta Capacidades de consulta avanzada en objetos de Microsoft Entra ID en la documentación de Microsoft Graph.

Las operaciones de Microsoft Dynamics AX 2012 fallan con "Logon failed"

  • Síntoma: Las operaciones que utilizan el conector Microsoft Dynamics AX contra AX 2012 fallan durante la ejecución, incluso aunque la prueba de conexión sea exitosa en Studio. El registro del Servicio REST del Conector Jitterbit Dynamics AX 2012 contiene:

    The server has rejected the client credentials.

    The logon attempt failed

  • Causa: El campo Nombre de dominio en la conexión de AX 2012 no está establecido al valor correcto. La autenticación de AX 2012 requiere que el Nombre de dominio sea la extensión del nombre de dominio DNS (por ejemplo, yourcompany.com), no un nombre de dominio corto o NetBIOS. Un valor de dominio incorrecto hace que AX rechace las credenciales válidas con un error de inicio de sesión, incluso cuando la prueba de conexión es exitosa.

  • Resolución:
    1. Abre la conexión de Dynamics AX 2012 en Studio.
    2. Establece el campo Nombre de dominio en tu extensión de nombre de dominio DNS (por ejemplo, yourcompany.com), no en un nombre de dominio corto/NetBIOS.
    3. Confirma que el Inicio de sesión sea el nombre de usuario de la cuenta de servicio de AX con los privilegios requeridos, y vuelve a escribir la Contraseña para descartar un valor obsoleto.
    4. Prueba la conexión y luego ejecuta nuevamente la operación.

Conector de NetSuite

Nota

NetSuite cuenta con una guía de solución de problemas dedicada que cubre problemas adicionales de conexión, esquema, configuración de actividad y rendimiento. Consulta Solución de problemas de NetSuite.

La creación, actualización o actualización de NetSuite falla con "is not a legal value for Country"

  • Síntoma: Una actividad NetSuite Create, Update o Upsert falla cuando el valor de origen de un campo de país no coincide con un valor enum Country de NetSuite:

    FaultString: org.xml.sax.SAXException: <country_value> is not a legal value for {urn:types.common_<version>.platform.webservices.netsuite.com}Country

  • Causa posible: La API SuiteTalk de NetSuite requiere que Country (y otros campos enumerados) sea uno de los valores enum predefinidos del WSDL (por ejemplo, _unitedStates). Se rechaza cualquier nombre para mostrar de país, código de país ISO o valor que no coincida exactamente con el enum del WSDL.

  • Resolución:
    • En la transformación que se asigna al destino de NetSuite, traduce el valor del país de origen al valor enum correspondiente de NetSuite antes de escribir. Un diccionario de referencia cruzada, una instrucción Case o una tabla de búsqueda funcionan para esto.
    • Construye la referencia cruzada a partir del enum Country definido en el WSDL de SuiteTalk de NetSuite que utiliza tu conector. Los valores válidos cambian entre versiones de WSDL, por lo que siempre verifica contra la versión de WSDL configurada actualmente en la conexión.
    • Aplica el mismo enfoque a cualquier otro campo respaldado por un enum de NetSuite (por ejemplo, State, Currency) donde los valores de origen no coincidan con el enum del WSDL.

Conector OData

Los conjuntos de entidades de OData v2 no se cargan con "No entity sets found"

  • Síntoma: Configurar una actividad Query de OData que apunte a un servicio OData v2.0 devuelve un error al obtener la lista de objetos, aunque la prueba de conexión sea exitosa:

    An error occurred while fetching the data:
Error while generating for query activity object list. The Exception is No entity sets found for the address provided.

  • Causa posible: La compatibilidad con servicios OData V2 se agregó al conector OData en la versión 11.59 del agente, a través de la configuración de conexión OData version. En agentes anteriores a 11.59, el conector solo admite OData V4, por lo que una conexión que apunte a un servicio OData V2 no puede llenar la lista de objetos. La misma falla ocurre en 11.59 o posterior si se deja OData version en V4 para un servicio OData V2.

  • Resolución:
    1. Para agentes privados, actualiza a la versión 11.59 o posterior. Los agentes de nube reciben la actualización automáticamente.
    2. En la conexión OData, establece OData version en V2 (el valor predeterminado es V4). Guarda y vuelve a probar la conexión.
    3. Reabre la actividad Query de OData. Los conjuntos de entidades ahora deberían cargarse.

OData: Microsoft Dynamics 365 devuelve solo los datos de la empresa predeterminada

  • Síntoma: Una conexión OData a un punto de conexión de Microsoft Dynamics 365 Finance and Operations devuelve datos solo de la empresa predeterminada del usuario, por lo que faltan registros de otras empresas en los resultados.
  • Causa posible: Por defecto, un punto de conexión OData de Dynamics 365 Finance and Operations devuelve solo los datos que pertenecen a la empresa predeterminada del usuario. Para otorgar a la conexión un alcance entre empresas (expandido), se debe agregar una cláusula de filtro entre empresas a la URL de metadatos OData de la conexión (la URL $metadata). En la URL de metadatos, ?cross-company=true por sí solo no aplica el alcance expandido.
  • Resolución: En la conexión OData, agrega una cláusula de filtro dataAreaId a la URL de metadatos OData, reemplazando usrt con tu identificador de área de datos, luego guarda y vuelve a probar:
?$filter=dataAreaId eq 'usrt'&cross-company=true

Para obtener información sobre cómo Dynamics 365 segmenta datos OData por empresa, consulta la documentación de Microsoft sobre comportamiento entre empresas.

Conectores Oracle

Oracle EBS: error de conexión "custom provider JAR file is not present"

  • Síntoma: La conexión a una instancia de Oracle E-Business Suite (EBS) falla con:

    Error connecting to Oracle EBS instance. Error is: The custom provider JAR file is not present in the Jitterbit Private Agent or it is not in the right location ($JITTERBIT_HOME/Connectors/Providers)

  • Posible causa: El conector Oracle EBS requiere que el controlador JDBC de Oracle (ojdbc8.jar) se coloque manualmente en el agente privado. Este archivo no se incluye con el agente y debe agregarse antes de que la conexión funcione.

  • Resolución:
    1. Descarga ojdbc8.jar del sitio web de Oracle (se requiere una cuenta de Oracle).
    2. Coloca ojdbc8.jar en el directorio $JITTERBIT_HOME/Connectors/Providers/ en el host del agente privado.
    3. Reinicia todos los agentes en el grupo de agentes.
    4. Prueba nuevamente la conexión de Oracle EBS.

Conectores Salesforce

Nota

El conector de Salesforce tiene una guía de solución de problemas dedicada que cubre autenticación, esquema, configuración de actividades, límites de registros y problemas de actividades en lote. Consulta Solución de problemas del conector Salesforce.

Eventos de Salesforce: no se pueden habilitar eventos después de reiniciar el agente

  • Síntoma: Después de reiniciar o reinstalar un agente privado, los eventos del conector Salesforce Events fallan al habilitarse, incluso cuando las credenciales de conexión son correctas.
  • Posible causa: Después de un reinicio, el archivo JAR del conector puede aún no estar presente en el agente. La habilitación de un evento requiere que el conector se descargue en el agente primero.
  • Resolución:
    1. Abre la configuración de la conexión de Salesforce Events en Studio.
    2. Haz clic en Test para probar la conexión. Esto fuerza la descarga del JAR del conector al agente.
    3. Después de que la prueba de conexión sea exitosa, intenta habilitar el evento nuevamente.

Eventos de Salesforce: "The channel specified is not valid" al habilitar una actividad de escucha de Change Data Capture

  • Síntoma: La habilitación de una operación que contiene una actividad de escucha de Salesforce Events Change Data Capture (CDC) falla con un error similar a:

    Unable to subscribe to [/data/<ObjectName>ChangeEvent:-1] [...]: 400::The channel specified is not valid {/data/<ObjectName>ChangeEvent}

  • Posible causa: El objeto no está seleccionado para Change Data Capture en Salesforce.

  • Resolución: En Salesforce, ve a Setup > Platform Tools > Integrations > Change Data Capture, agrega el objeto a Selected Entities y luego habilita la operación nuevamente. Para ver los pasos completos, consulta Selecciona las entidades que generan eventos.

Eventos de Salesforce: limitaciones de actividades de escucha

Los siguientes comportamientos de las actividades de escucha de Salesforce Events (Subscribe Event y las actividades Subscribe Insert, Update y Delete CDC Event) son esperados y no indican un defecto del conector:

  • No se pueden habilitar eventos porque se alcanzó el número máximo de suscriptores. La instancia de Salesforce limita la cantidad de clientes concurrentes (suscriptores). Cuando se alcanza ese límite, no se pueden habilitar más eventos. Reduce la cantidad de suscriptores activos conectados a la instancia.
  • Faltan símbolos de medida como $ y % en la respuesta. Estos símbolos no se devuelven, por diseño de la API de Salesforce.
  • Los campos sin modificar se devuelven como null en las respuestas de Change Data Capture (CDC). Para las actividades de CDC, solo se rellenan los campos modificados; los campos sin modificar se devuelven como null, por diseño de la API de Salesforce.

Conector SAP

Múltiples actividades de SAP en una operación fallan en tiempo de ejecución

  • Síntoma: Una operación que contiene más de una actividad de SAP, o que combina una actividad de SAP con una actividad de NetSuite, Salesforce, Salesforce Service Cloud, ServiceMax o SOAP, se implementa sin errores de validación pero falla al ejecutarse.
  • Causa posible: Las operaciones que mezclan estos tipos de actividades parecen válidas en Studio y se pueden implementar correctamente, pero estas combinaciones no son compatibles en tiempo de ejecución. Las reglas de validación de operaciones no marcan este patrón como un error en el tiempo de diseño. Este es un problema conocido de Studio documentado.
  • Resolución:
    • Diseña cada operación para que contenga solo una actividad de SAP, sin otras actividades de SAP, NetSuite, Salesforce, Salesforce Service Cloud, ServiceMax o SOAP en la misma operación.
    • Si necesitas datos de múltiples sistemas en un único flujo de trabajo, divide la lógica en operaciones separadas y encadénalas usando acciones de operación.

SAP RFC: "No RFC authorization for function module BAPI_TRANSACTION_COMMIT"

  • Síntoma: Una actividad de RFC de SAP falla en tiempo de ejecución con:

    JCoException occurred No RFC authorization for function module BAPI_TRANSACTION_COMMIT

  • Causas posibles:

    • La cuenta de usuario de SAP en la conexión no tiene autorización S_RFC para BAPI_TRANSACTION_COMMIT o sus grupos de funciones relacionados.
    • El módulo de función BAPI_TRANSACTION_COMMIT no está configurado como habilitado para acceso remoto en el sistema SAP.
    • La transformación de solicitud anterior a la actividad no establece el campo de control de confirmación.

  • Resolución:

    • En el sistema SAP, confirma que el módulo de función BAPI_TRANSACTION_COMMIT esté habilitado para acceso remoto.
    • En la transformación de solicitud anterior a la actividad de RFC de SAP, establece el campo BAPI_COMMIT en true.
    • Verifica que la cuenta de usuario de SAP referenciada en la conexión tenga autorización S_RFC para BAPI_TRANSACTION_COMMIT y todos los grupos de funciones relacionados.
    • Si el problema persiste, comunícate con tu administrador de SAP BASIS para revisar las asignaciones de objetos de autorización del usuario.

La conexión SAP falla con "Invalid language key"

  • Síntoma: Una conexión de SAP falla durante la inicialización con un error sobre la clave de idioma:

    Connector Error: AdapterResourceException: Error while creating Destination. 00024Invalid language key when configuring the text environment.

  • Causa posible: El código de Idioma configurado en el endpoint de SAP no es válido para el sistema SAP de destino: el código no está instalado ni es compatible con ese sistema, o está mal escrito o tiene mayúsculas incorrectas (por ejemplo, en en lugar de EN). SAP rechaza la clave inválida cuando inicializa el entorno de texto del destino.

  • Resolución:
    1. Edita el endpoint de SAP en Studio y establece el campo Idioma con un código de idioma de dos letras compatible (por ejemplo, EN para inglés).
    2. Verifica que el valor coincida con un idioma instalado y activo en el sistema SAP de destino. Si no estás seguro, confirma el idioma predeterminado del usuario de integración en el perfil de usuario de SAP y úsalo.
    3. Prueba la conexión desde Studio para confirmar que la inicialización se realiza correctamente antes de redesplegara la operación.

Conector de ServiceNow

Las primeras ejecuciones de operaciones son lentas después del reinicio del agente o en agentes en la nube

  • Síntoma: Las operaciones que utilizan el conector de ServiceNow se ejecutan lentamente en dos escenarios:

    • En agentes privados, la primera operación después del reinicio del agente puede tardar varios minutos; las ejecuciones posteriores son rápidas.
    • En agentes en la nube, las ejecuciones son intermitentemente lentas, tardando minutos cada vez que se actualiza la caché de metadatos del conector.

    Esto puede causar tiempos de espera agotados en la API descendente.

  • Causa posible: El conector almacena en caché los metadatos de ServiceNow de forma agresiva. Después de un reinicio del agente en un agente privado (o en cada ejecución de un agente en la nube que no preservó la caché), la primera operación debe reconstruir la caché, lo que tarda varios minutos.

  • Resolución:
    • En un agente privado, mitiga la lentitud posterior al reinicio agregando getcolumnsmetadata=onUse a las Opciones avanzadas del endpoint de ServiceNow. Esta configuración solo es efectiva en agentes privados.
    • Para un rendimiento consistente en agentes en la nube, llama a la API REST de ServiceNow a través del conector de HTTP v2 en lugar de usar el conector de ServiceNow. El conector HTTP v2 no almacena metadatos en caché y evita la demora de reconstrucción.

Conector de ServiceNow v2

ServiceNow v2: Un objeto no aparece listado por su nombre de conector de ServiceNow

  • Síntoma: Un objeto que se puede seleccionar por un nombre familiar en el conector de ServiceNow no se encuentra por ese mismo nombre en el conector de ServiceNow v2.
  • Causa: El uso de la API REST de ServiceNow por parte del conector de ServiceNow v2 expone los objetos utilizando el nombre real de la tabla backend de ServiceNow, que puede diferir del nombre utilizado para el mismo objeto en el conector de ServiceNow. Por ejemplo, el objeto llamado System en el conector de ServiceNow corresponde a Sys en el conector de ServiceNow v2.
  • Resolución: En ServiceNow, busca el nombre de tabla real del objeto en System Definition > Tables, luego busca ese nombre en la configuración de actividad del conector de ServiceNow v2.

Conector de Shopify

Shopify: Las selecciones de objetos de actividad pueden cambiar después de la actualización de versión de API

  • Síntoma: Después de cambiar la versión de la API en una conexión Shopify, una o más actividades de Shopify devuelven errores o se comportan de forma inesperada, y un objeto configurado o subobjeto parece haber cambiado.
  • Causa posible: Shopify lanza nuevas versiones de API trimestralmente y deja de ser compatible con versiones anteriores después de 12 meses. Cuando cambias a una versión de API diferente, los objetos o subobjetos que no están disponibles en la nueva versión pueden dejar de ser seleccionables, lo que provoca que la selección configurada de la actividad cambie cuando se actualiza la configuración.
  • Resolución:
    1. Después de cambiar la versión de la API de Shopify en la conexión, abre cada configuración de actividad de Shopify afectada.
    2. Haz clic en Actualizar para recargar los objetos disponibles para la nueva versión de la API.
    3. Revisa las selecciones de objetos y subobjetos para confirmar que reflejan tu intención en la nueva versión.
    4. Actualiza las selecciones que cambiaron a los objetos de reemplazo correctos.
    5. Vuelve a desplegar y realiza nuevas pruebas de las operaciones afectadas.
    6. Para obtener información sobre los plazos de deprecación de versiones de la API de Shopify, consulta el registro de cambios de Shopify.

Conector Snowflake

Snowflake: Las conexiones basadas en contraseña fallan después de la deprecación de autenticación

  • Síntoma: Las operaciones que se conectan a Snowflake usando el tipo de autenticación Contraseña (Deprecated) han comenzado a fallar después de funcionar previamente, por ejemplo con:

    HttpErrorResponse: Error opening connection. Exception is Failed to authenticate: MFA authentication is required, but none of your current MFA methods are supported for programmatic authentication.

  • Causa posible: Snowflake está eliminando la autenticación de un solo factor (solo contraseña), incluyendo las cuentas de tipo LEGACY_SERVICE requeridas para este tipo de autenticación. Snowflake migra cuentas LEGACY_SERVICE a TYPE=SERVICE de forma progresiva, por cuenta, lo que bloquea completamente la autenticación basada en contraseña; algunas cuentas también tienen autenticación multifactor (MFA) habilitada, que es incompatible con esta conexión programática completamente automatizada, ya que MFA requiere intervención humana. Consulta Contraseña (Deprecated) para conocer la línea de tiempo de deprecación.

  • Resolución: Actualiza la conexión del conector Snowflake en Studio para usar autenticación OAuth o Key-Pair, y configura la cuenta de usuario de Snowflake en consecuencia, asegurándote de que no esté inscrita en MFA.

Snowflake: La instancia de desarrollador está durmiendo, las tablas de metadatos no se están rellenando

  • Síntoma: Al configurar una actividad Snowflake, la lista de objetos disponibles no se rellena o aparece vacía, aunque la prueba de conexión sea exitosa.
  • Causa posible: Las instancias de desarrollador de Snowflake entran en estado de reposo cuando no se ha accedido a ellas recientemente. Aunque la prueba de conexión puede ser exitosa contra una instancia durmiendo, es posible que la instancia no devuelva los metadatos de tablas y objetos.
  • Resolución:
    1. Inicia sesión en la interfaz web de Snowflake para despertar la instancia.
    2. Vuelve a abrir la conexión de Snowflake en Studio y haz clic en Prueba para volver a probar las credenciales.
    3. Vuelve a abrir la configuración de la actividad para actualizar la lista de objetos disponibles.

Snowflake Query: La falta de coincidencia de mayúsculas y minúsculas en el nodo raíz de esquema plano causa error ProcessFlatStream

  • Síntoma: Una actividad de Consulta de Snowflake que utiliza un esquema plano falla en tiempo de ejecución con:

    StartElement() error, starting element does not match with the root.
qName= "<table_name_lowercase>", root name="<TABLE_NAME_UPPERCASE>"

ProcessFlatStream error

    Este error ocurre cuando la consulta incluye una cláusula WHERE, una cláusula LIMIT o una referencia de variable en una cláusula WHERE.

  • Causa posible: El conector de Snowflake devuelve el nombre de la tabla en minúsculas en la respuesta XML. Cuando Studio genera un esquema plano a partir de la consulta, el nombre del nodo raíz se crea en mayúsculas. La diferencia de mayúsculas y minúsculas entre el nodo raíz del esquema (mayúsculas) y el nodo raíz de la respuesta XML (minúsculas) causa que el procesamiento de flujo plano falle.

  • Resolución: Elige una de las siguientes opciones:
    • En el esquema plano, cambia el nombre del nodo raíz a minúsculas para que coincida con la salida del conector. Por ejemplo, renombra SALES_ORDERS a sales_orders.
    • Utiliza el esquema espejo con asignación predeterminada en lugar de un esquema plano construido manualmente. El esquema espejo deriva su estructura directamente de la respuesta del conector y no tiene esta diferencia de mayúsculas y minúsculas.

Snowflake Merge: stageName y fileContent no aparecen en el esquema de solicitud para etapas externas

  • Síntoma: Una actividad de Merge de Snowflake configurada para una etapa externa muestra un esquema de solicitud sin los campos stageName y fileContent. La misma actividad configurada para una etapa interna expone ambos campos.
  • Causa posible: Las etapas externas son referencias de solo lectura a archivos que ya existen en el almacenamiento en la nube externo (S3, GCS o Azure Blob). La actividad de Merge no puede cargar contenido de archivos en una etapa externa, por lo que el esquema omite los campos que impulsan esa carga.
  • Resolución:
    • Cuando la actividad se dirige a una etapa externa, asegúrate de que los archivos de datos ya estén presentes en la ubicación de almacenamiento en la nube a la que la etapa hace referencia. La actividad de Merge lee directamente de esos archivos; no se necesita el campo fileContent.
    • Cuando necesites insertar contenido de archivo desde la operación, configura la actividad de Merge para utilizar una etapa interna. El esquema expone entonces stageName y fileContent.

Snowflake Insert o Merge: Errores de sintaxis SQL por caracteres especiales

  • Síntoma: Una actividad de Insert o Merge de Snowflake falla con un error de compilación SQL como:

    SQL compilation error:
syntax error line 1 at position <n> unexpected '<token>'.

    Los valores de columna también pueden aparecer mal asignados, con datos de un campo apareciendo en la columna incorrecta.

  • Causas posibles:

    • Los valores de campo que contienen comillas simples (por ejemplo, un valor como corner's) no se escapan antes de incluirse en la carga útil SQL. La comilla sin escape termina la cadena prematuramente, causando que el resto del valor se interprete como sintaxis SQL en lugar de datos.
    • El nombre de una columna de destino contiene un carácter especial, como un guión (por ejemplo, Zip-Code). Snowflake requiere que un identificador que contiene un carácter especial esté entrecomillado; sin entrecomillar, produce un error de sintaxis en el guión.

  • Resolución:

    • Para valores que contienen comillas simples: En la Configuración opcional de la conexión de Snowflake, habilita Escape special characters (Escapar caracteres especiales). Esto escapa automáticamente las comillas simples en las cargas útiles de las actividades de Insert e Invoke Stored Procedure. Para actividades de Merge, o como alternativa para Insert, utiliza SQLEscape en la asignación de transformación para escapar las comillas simples en los valores de campo afectados antes de que lleguen a la actividad.
    • Para nombres de columna que contienen caracteres especiales: Confirma que Use quote for Snowflake identifiers (Usar comillas para identificadores de Snowflake) esté habilitado en la conexión (habilitado de forma predeterminada).

Snowflake: Error de espacio en memoria de Java al consultar conjuntos de datos grandes

  • Síntoma: Una actividad Query de Snowflake falla con el siguiente error cuando la consulta devuelve un gran número de filas:

    Error executing query activity. Exception is Java heap space

    El conector reporta el error de esta forma porque envuelve el error subyacente de Java, que aparece más adelante en el seguimiento de pila:

    Caused by: java.lang.OutOfMemoryError: Java heap space

    Si este error ocurre en consultas que devuelven pocas filas, o el mismo agente también falla con errores de memoria mediante otros conectores, es más probable que la causa sea la asignación general de memoria del agente que el tamaño del conjunto de resultados. Consulta Espacio en memoria de Java: OutOfMemoryError.

  • Causa posible: El conector de Snowflake carga el conjunto de resultados de la consulta completa en la memoria de JVM antes de pasarlo a la transformación. Con conjuntos de resultados muy grandes, esto agota la memoria de Tomcat JVM en el agente privado.

  • Resolución: Para grandes volúmenes de consultas, utiliza el conector de base de datos con un controlador JDBC de Snowflake en lugar del conector de Snowflake. El conector de base de datos no almacena el conjunto de resultados completo en memoria, por lo que puede manejar volúmenes de consultas mucho más grandes. Instala el controlador JDBC de Snowflake en el agente privado y luego configura una conexión de base de datos que lo utilice. En el agente 12.x y posteriores, esa conexión de base de datos también necesita enableArrowResultFormat=false&jdbc_query_result_format=json en su cadena de conexión; consulta Snowflake: Las operaciones fallan en el agente 12.x.

    Si necesitas mantener el conector de Snowflake, cualquiera de lo siguiente puede reducir la presión de memoria, aunque ninguno garantiza ser suficiente para conjuntos de datos de millones de filas:

    • Divide la consulta en lotes utilizando las cláusulas LIMIT y OFFSET de SQL, ejecutando la operación repetidamente con compensaciones incrementales hasta que se procesen todas las filas.
    • Aumenta el tamaño de memoria de Tomcat JVM en el agente privado (consulta Memoria de montón de Tomcat).

Snowflake: Las operaciones fallan en el agente 12.x

  • Síntoma: En un agente privado que ejecuta la versión 12.x, las operaciones que consultan Snowflake a través de un controlador JDBC de Snowflake (una conexión de base de datos o un script DBExecute) fallan en tiempo de ejecución, aunque la prueba de conexión se realice correctamente. El error hace referencia a la capa de memoria Arrow del controlador, por ejemplo:

    JDBC driver internal error: exception creating result java.lang.ExceptionInInitializerError at net.snowflake.client.jdbc.internal.apache.arrow.memory.unsafe.UnsafeAllocationManager

    o:

    JDBC driver internal error: exception creating result java.lang.NoClassDefFoundError: Could not initialize class net.snowflake.client.jdbc.internal.apache.arrow.memory.RootAllocator

  • Causa posible: De forma predeterminada, el controlador JDBC de Snowflake devuelve los resultados de la consulta en el formato Apache Arrow, que no es compatible con la versión 12.x del agente y posteriores. Consulta el artículo de solución de problemas de Snowflake sobre este error de módulo Java para obtener más detalles. La prueba de conexión no devuelve ningún conjunto de resultados, por lo que aún se realiza correctamente mientras que las consultas fallan. Actualizar la versión del controlador JDBC no lo resuelve.

  • Resolución: Establece enableArrowResultFormat en false y jdbc_query_result_format (o JDBC_QUERY_RESULT_FORMAT) en json para que el controlador devuelva los resultados en JSON en lugar de Arrow:
    • Conector de base de datos: Agrega enableArrowResultFormat=false&jdbc_query_result_format=json a la cadena de conexión de Snowflake, en el campo Additional Connection String Parameters (o el campo Connection String, si se selecciona Use Connection String).
    • Conector de Snowflake: En Optional settings > Connection Custom Properties, agrega enableArrowResultFormat con un valor de false. Una fila JDBC_QUERY_RESULT_FORMAT con un valor de JSON ya está presente allí de forma predeterminada.

Luego guarda, reintenta la conexión y vuelve a ejecutar la operación.

En un agente privado, puedes aplicar la solución a nivel de JVM para que no sea necesario repetirla por conexión, agregando --add-opens=java.base/java.nio=ALL-UNNAMED a CATALINA_OPTS:

=== "Linux"

    Agrega la siguiente línea a `/opt/jitterbit/tomcat/bin/setenv.sh`:

    ```sh
    export CATALINA_OPTS="$CATALINA_OPTS --add-opens=java.base/java.nio=ALL-UNNAMED"
    ```

    Luego reinicia el agente.

=== "Windows"

    1.  Abre el Editor del Registro y busca la siguiente clave:

        ```txt
        HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java
        ```

    2.  Abre la subclave **Options**.
    3.  En el campo **Value data**, agrega `--add-opens=java.base/java.nio=ALL-UNNAMED` a las opciones de Java existentes.
    4.  Haz clic en **Ok**.
    5.  Reinicia el agente.

=== "Docker"

    Usa una de las siguientes estrategias para aplicar la configuración:

    1.  Actualiza el Dockerfile y reconstruye la imagen de Docker:

        ```
        docker build -t my-agent .
        ```

    2.  Inclúyelo en el comando `run` de Docker:

        ```
        docker run -e CATALINA_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED" my-agent
        ```

    3.  Inclúyelo en `docker-compose.yml` y reinicia el contenedor:

        ```
        environment:
          - CATALINA_OPTS=--add-opens=java.base/java.nio=ALL-UNNAMED
        ```

Conector SOAP

Error de implementación de SOAP: "No WSDL with locator"

  • Síntoma: La implementación de un proyecto que incluye una conexión SOAP, o una actividad SOAP Request o SOAP Response de API, falla con:

    Failed to deploy - Internal Error: No WSDL with locator

  • Posibles causas:

    • El WSDL se eliminó, se reimportó o su referencia interna se rompió, por lo que el proyecto hace referencia a un identificador de WSDL que ya no existe.

    • El proyecto se implementó o se transfirió a otro entorno, antes de la versión Harmony 12.9, cuando la implementación de un proyecto podía eliminar archivos WSDL que aún estaban en uso. La versión 12.9 previene la eliminación, pero un WSDL eliminado antes debe volver a cargarse.

  • Resolución:

    1. Vuelve a cargar el WSDL para el componente afectado:

      • Para una conexión SOAP, abre la conexión y selecciona Upload URL o Upload file (no Select existing), vuelve a cargar el WSDL, revisa la configuración de Port y Select methods, y luego haz clic en Save Changes.
      • Para una actividad SOAP Request o SOAP Response de API, abre la actividad y vuelve a cargar el WSDL en el paso 1 de su configuración.

      Si la carga muestra un error de validación, consulta Requisitos de carga de WSDL.

    2. Revisa cualquier transformación que herede esquemas del WSDL recargado y regeneralos si es necesario.

    3. Reimplementa el proyecto.

    4. Si el proyecto tiene múltiples WSDLs y no está claro cuál se ve afectado, consulta Solución de problemas de conexión SOAP para identificarlo desde una exportación JSON.

WSDL de SOAP: schemaLocation debe usar referencias relativas

  • Síntoma: Una conexión SOAP que hace referencia a un WSDL con archivos de esquema XSD importados falla al cargar o produce errores de resolución de esquema en tiempo de diseño. Cargar el WSDL puede mostrar un error como:
Error al analizar WSDL: ENOENT: no such file or directory, open '<path>/types.xsd'

donde types.xsd es el nombre del archivo faltante. Cuando el WSDL está en un archivo ZIP, el error comienza con Failed to parse WSDL file 'filename': en su lugar, donde filename es el nombre del archivo WSDL en el archivo ZIP.

  • Posibles causas:

    • El WSDL utiliza URLs absolutas en sus atributos schemaLocation para archivos XSD importados (por ejemplo, http://example.com/schema.xsd). El agente no puede obtener esquemas desde URLs remotas absolutas al cargar un WSDL importado localmente.

    • El WSDL importa un archivo XSD que no se cargó con él. Los archivos XSD que el WSDL importa utilizando rutas relativas deben cargarse en un archivo ZIP junto con el WSDL.

  • Resolución:

    1. Edita el WSDL para que todas las referencias schemaLocation utilicen rutas relativas (por ejemplo, schema.xsd en lugar de http://example.com/schema.xsd).

    2. Coloca todos los archivos XSD referenciados en el mismo directorio que el WSDL, o en la ubicación relativa que cada schemaLocation especifica. Agrega el WSDL y los archivos XSD a un archivo ZIP y carga el archivo ZIP en la conexión SOAP usando Upload file.

    3. Para todos los requisitos de carga, consulta WSDL upload requirements.

El conector SOAP reescribe los prefijos de espacios de nombres XML y la estructura

  • Síntoma: El sobre XML producido por una actividad SOAP no coincide con los prefijos de espacios de nombres literales o la estructura del WSDL fuente (por ejemplo, el conector sustituye xmlns:ns1 por xmlns:glob). Los servicios SOAP estrictos que comparan el texto exacto del prefijo rechazan la solicitud.
  • Posible causa: El motor de transformación procesa los mensajes SOAP como XML estructurado, no como texto literal. Produce una carga útil semánticamente equivalente que puede utilizar prefijos de espacios de nombres diferentes al WSDL fuente.
  • Resolución: Para servicios SOAP que requieren una estructura XML literal, omite el conector SOAP y construye la carga útil de solicitud como una cadena:
    1. Crea una conexión HTTP v2 que apunte a la URL del servicio SOAP.
    2. En una transformación, construye el sobre SOAP como una cadena, concatenando literales de cadena y valores asignados con el operador +. Alternativamente, lee una plantilla desde un archivo y sustituye valores dinámicos con Replace.
    3. En la actividad POST de HTTP v2, utiliza el esquema de solicitud predeterminado (no cargues un esquema de solicitud personalizado) y asigna la cadena del sobre SOAP construida al campo body de ese esquema. El conector envía el valor body tal cual, preservando el XML literal.
    4. Establece el encabezado Content-Type en text/xml o application/soap+xml, y establece el encabezado SOAPAction si el servicio lo requiere.
    5. Lee la respuesta del servicio desde el campo responseContent del esquema de respuesta predeterminado de la actividad.

SOAP: Los mensajes MTOM/XOP no son compatibles

Conector VTEX

La prueba de conexión falla con "You don't have permission to access this resource"

  • Síntoma: Una prueba de conexión VTEX falla con un error de permisos en Studio aunque las mismas credenciales funcionen en herramientas externas como Postman.
No tienes permiso para acceder a este recurso
  • Posible causa: Al usuario de VTEX o a la clave de aplicación asociada a la conexión le falta uno o más permisos que el conector utiliza para validar la conexión. Estos permisos son más estrictos que los necesarios para el acceso básico a datos.
  • Resolución:
    1. En el portal de administración de VTEX, abre el perfil de acceso asignado al usuario o a la clave de aplicación que Jitterbit está utilizando.
    2. Confirma que el perfil de acceso incluya la función License Manager con acceso al recurso Get account by identifier.
    3. Guarda el perfil y vuelve a probar la conexión de VTEX en Studio.

Conector de Workday

Workday: WSDL v42.0 y v42.1 devuelven errores para servicios específicos

  • Síntoma: Las operaciones que utilizan el conector de Workday configurado con la versión 42.0 o 42.1 de WSDL fallan al acceder a los servicios web Human_Resources o Resource_Management.
  • Posible causa: Se sabe que WSDL v42.0 devuelve errores para los servicios Human_Resources (v42.0) y Resource_Management (v42.0). Se sabe que WSDL v42.1 devuelve errores para el servicio Human_Resources (v42.1). Se trata de problemas conocidos específicos de esas versiones de WSDL.
  • Resolución:
    1. En la configuración de la conexión de Workday, cambia la versión de WSDL a 41.x o 43.0 o posterior para las operaciones que utilicen los servicios Human_Resources o Resource_Management.
    2. Prueba la conexión y vuelve a ejecutar las operaciones afectadas para confirmar que el problema se ha resuelto.

Workday: La prueba de conexión falla con "The task submitted is not authorized"

  • Síntoma: Una prueba de conexión de Workday falla con:

    Error occurred while opening connection. The Exception is Processing error occurred. The task submitted is not authorized.

    Este error puede ocurrir con ambos tipos de autenticación: Basic Auth y JWT Bearer. Ten en cuenta que las operaciones pueden ejecutarse correctamente en tiempo de ejecución incluso cuando la prueba de conexión devuelve este error, porque la prueba llama a un servicio específico de Workday (Get_Message_Template_Translation_Request) que requiere un permiso que es posible que la ISU no tenga, mientras que las operaciones reales de integración llaman a servicios diferentes.

  • Posibles causas:

    • El usuario del sistema de integración (ISU) no ha sido asignado al grupo de seguridad Setup Administrator en Workday. La llamada de prueba de conexión del conector se rechaza si el ISU carece de esta membresía del grupo de seguridad.
    • El campo Workday Host contiene un valor incorrecto. Un host incorrecto causa que la conexión falle antes de que se intente la autenticación.

  • Resolución:

    1. Verifica que el valor de Workday Host en la configuración de la conexión sea correcto. El host debe ser la URL base de tu inquilino de Workday (por ejemplo, https://wd5-impl-services1.workday.com/). Puedes confirmar el valor correcto desde la página View API Client de Workday.
    2. En la instancia de Workday, abre la tarea Assign Users to User-based Security Group, selecciona Setup Administrator y confirma que el ISU aparece en la lista bajo System Users. Si no aparece, agrega el ISU. Para ver los pasos completos, consulta Requisitos previos.
    3. Confirma que la tarea Configure Web Service Security también se haya completado para el ISU, tal como se describe en la página Requisitos previos.
    4. Vuelve a probar la conexión.