Solución de problemas de operaciones en Jitterbit Studio

Esta guía cubre errores y comportamientos inesperados al construir, desplegar y ejecutar operaciones en Jitterbit Studio, incluyendo operaciones, transformaciones, scripts y funciones, y validación en tiempo de diseño. Si se está solucionando problemas de un conector específico, consulta Solución de problemas de conectores.

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

• Errores HTTP y API

  • 504 Gateway Timeout
  • 507 Insufficient Storage
  • 502 Bad Gateway

• Errores en tiempo de diseño

  • Errores de validación de operación comunes
  • Errores de regla de validación HTTP
  • Los nombres de componentes deben ser únicos después de importar un proyecto
  • Los bloques de conector solo para agente privado se importan a un entorno de agente en la nube
  • Cargar un archivo de esquema lo reemplaza en todo el proyecto
  • La implementación de la plantilla de proceso de Marketplace falla debido a una falta de coincidencia de esquema
  • Studio se vuelve lento o no responde con proyectos muy grandes

• Errores de sistema y recursos

  • La fragmentación no se respeta cuando la fuente es un conector basado en SDK
  • Actualizaciones de variables perdidas en operaciones multi-thread fragmentadas
  • Error al crear directorio temporal
  • Mensajes de registro de operación truncados en aproximadamente 100 KB
  • El registro de depuración de operación expone PII y credenciales en texto plano

Pasos de diagnóstico

Estos pasos se aplican a casi cualquier fallo de operación y son el punto de partida recomendado antes de investigar un error específico.

Probar la conexión

Para cualquier operación que use conectores, en la conexión, haz clic en el botón Test para asegurar que la conexión sea exitosa.

Para conectores basados en Connector SDK implementados en operaciones que se ejecutan en agentes privados, hacer clic en Test también asegura que la versión más reciente del conector se descargue en el agente (a menos que la política de organización Disable Auto Connector Update esté habilitada).

Revisar los registros de operación

Revisa los registros de operación para cualquier información escrita durante la ejecución.

Dependiendo del tipo de agente, hay datos de registro adicionales disponibles:

• Habilita el registro de depuración de operación (para agentes en la nube o para agentes privados).
• Habilita el registro detallado de conector (solo agentes privados).
• Revisa los registros del agente (solo agentes privados).

Aislar fallos específicos del agente

Si una operación falla en algunos agentes pero tiene éxito en otros dentro del mismo grupo de agente privado, usa la opción Run on dedicated agent para dirigir la operación a un agente específico. Esto te permite reproducir e investigar el fallo en el agente problemático sin desconectar el resto del grupo.

Para configurar esta opción, abre la configuración de la operación, selecciona la pestaña Options y configura Run on dedicated agent.

Ejecución y programación de operaciones

Operaciones atascadas en estado Submitted o Running

• Síntoma: Una operación no se completa como se esperaba. Permanece en estado Submitted o Running y nunca progresa, o se cancela con el mensaje:

  Long running operation canceled by System
  

  La cancelación puede ocurrir después de que la operación ha estado ejecutándose por un tiempo o poco después de que comienza, y no necesariamente refleja cuánto tiempo se ejecutó realmente la operación.

• Posibles causas:

  • Un agente privado perdió su conexión con la plataforma Harmony y no pudo reportar el estado de la operación. La plataforma continúa mostrando la operación como Running y puede cancelarla como aparentemente colgada, incluso cuando la operación se completó en el agente. Esto puede afectar operaciones que normalmente terminan en segundos.
  • La operación se completó, pero su estado final no se reportó a Harmony, por lo que continúa apareciendo como Running hasta que se agota el tiempo de espera.
  • El grupo de agentes está bajo carga pesada y es lento para recoger o actualizar operaciones en cola.
  • La operación está atascada específicamente en Submitted: el mensaje de ejecución se puso en cola pero ningún agente en el grupo lo ha aceptado, porque los agentes están sin conexión, no están saludables, o no tienen capacidad libre para aceptar nuevas operaciones (por ejemplo, cada hilo de trabajo está ocupado).

• Resolución:

  • Para agentes privados, confirma que el agente tenga un estado Running en la página Agents de la Management Console, revisa los registros del agente privado para identificar problemas de conexión y verifica que la conexión de red entre el agente y la plataforma Harmony sea estable.
  • Revisa los registros de operación para confirmar qué sucedió durante la ejecución. El mensaje de cancelación puede aparecer incluso para operaciones que se ejecutaron brevemente, por lo que no necesariamente indica una operación que se ejecutó durante mucho tiempo. Los registros también pueden revelar un error específico que abordar, como 401 Unauthorized (verifica las credenciales) o 429 Too Many Requests. Un 429 de un endpoint de destino se puede mitigar reduciendo la tasa de solicitudes o agregando lógica de reintentos; un 429 de la puerta de enlace de API en la nube administrada por Jitterbit es su límite de plataforma de 200 solicitudes por minuto, así que distribuye las llamadas a lo largo del tiempo o ejecuta las API afectadas en agentes privados.
  • Mantén los agentes privados en una versión actual. Las versiones posteriores del agente mejoran la resiliencia del agente y reducen la cancelación prematura de operaciones.
  • Intenta cancelar las operaciones afectadas. La cancelación está disponible para operaciones en estado Submitted, Received, Pending o Running desde la página Runtime de la Management Console, la tabla de registros de operación o el estado de ejecución de una operación en el lienzo de diseño.
  • Si la operación afectada se ejecuta según una programación y nunca se inicia, consulta Operaciones programadas que no se ejecutan.
  • Si no se pueden cancelar las operaciones, si el problema se repite o si muchas operaciones se ven afectadas a la vez, contacta con el soporte de Jitterbit, ya que estos casos pueden requerir resolución del lado del servidor.

Operaciones programadas que no se ejecutan

• Síntoma: Una operación configurada con una programación de operación no se ejecuta en la hora programada o se envía pero permanece en estado Pending o Received.
• Posibles causas:
  • La programación se asignó a la operación en Studio pero el proyecto no se ha implementado. Las programaciones asignadas en Studio no entran en vigor hasta que se implementa el proyecto.
  • La programación está deshabilitada.
  • Existe una configuración incorrecta de zona horaria en la configuración de programación.
  • Para agentes privados, el servicio de programación no se está ejecutando.
  • El agente asociado con el entorno está sin conexión o no está en buen estado.
  • Los cambios implementados en un proyecto no se han sincronizado completamente con el agente.
  • El grupo de agentes está saturado de recursos. Un acumulamiento de operaciones de larga duración o un uso sostenido de CPU o memoria alta pueden impedir que un grupo de agentes recoja operaciones programadas a tiempo.
• Resolución:
  • Confirma que el proyecto se ha implementado desde que se asignó la programación a la operación.
  • Confirma que la programación está habilitada. Las programaciones se pueden habilitar o deshabilitar solo desde la página Projects de la Management Console, en las pestañas Operations y Schedules.
  • Revisa la configuración de programación, prestando especial atención a la configuración de zona horaria. Para obtener más detalles, consulta Zonas horarias de operación.
  • Para agentes privados, verifica que el agente esté en línea y en buen estado en la página Agents de la Management Console y confirma que el servicio de programación se está ejecutando en la máquina del agente. En Windows, comprueba que Jitterbit Scheduler y Jitterbit Scheduler Service se estén ejecutando en el Administrador de tareas. En Linux y Docker, usa el comando jitterbit status.
  • Vuelve a implementar el proyecto para forzar que la programación se resincronice con el agente.
  • Si las operaciones están atrapadas en estado Pending, cancélalas a través de la página Runtime de la Management Console y reinicia el servicio del agente.
  • Si los fallos de programación se correlacionan con la carga, reduce el número de operaciones concurrentes de larga duración. En agentes privados, también revisa el uso de CPU y memoria y equilibra las operaciones programadas con la capacidad del agente (un agente privado puede ejecutar hasta el doble de su número de núcleos de CPU en operaciones concurrentes).
  • Si una operación programada se envía pero luego se detiene en lugar de nunca iniciarse, consulta Operaciones atrapadas en estado Submitted o Running.

El diccionario o la variable global está vacía después de que una operación se ejecuta de forma asincrónica

• Síntoma: Un diccionario o una variable global que se completa dentro de una operación secundaria está vacía o mantiene su valor anterior cuando la operación principal la lee después de invocar la secundaria de forma asincrónica.
• Causa posible: Cuando se invoca una operación de forma asincrónica (el Run type de la herramienta Invoke Operation establecido en Asynchronously, o RunOperation llamado con runSynchronously establecido en false), la operación secundaria se ejecuta en un hilo separado y la operación principal continúa sin esperar. Las variables globales y los diccionarios se pasan a la operación secundaria por valor en lugar de por referencia y no son seguros para subprocesos, por lo que los cambios realizados en la operación secundaria no se reflejan en la operación principal. La operación principal también puede leer el valor antes de que la operación secundaria termine.
• Resolución:
  • Si la operación principal depende de valores que produce la operación secundaria, invoca la operación secundaria de forma sincrónica (el Run type de la herramienta Invoke Operation establecido en Synchronously, o RunOperation ejecutado de forma sincrónica, que es el valor predeterminado) para que la operación secundaria se complete y la operación principal herede sus cambios de variables globales.
  • Para compartir datos entre operaciones que deben ejecutarse de forma independiente, persiste los datos con funciones de caché (WriteCache y ReadCache) en lugar de depender de un diccionario o una variable global entre subprocesos. De forma predeterminada, las funciones de caché se limitan a 100 llamadas combinadas por minuto por organización.
  • Insertar un retraso fijo (por ejemplo, con la función Sleep) añade latencia y no garantiza que la operación secundaria haya terminado; ejecuta la operación de forma sincrónica en su lugar.
• Relacionado: Para el comportamiento equivalente en operaciones multi-subproceso fragmentadas, consulta Variable updates lost in chunked multi-threaded operations.

Errores de conexión y autenticación

Certificado de Salesforce: falta de coincidencia del Nombre Alternativo del Asunto (SAN)

• Symptom: A Salesforce connection to a sandbox or an org with Enhanced Domains enabled fails with:

  Certificate for <url> doesn't match any of the subject alternative names
  

• Possible causes:

  • The certificate does not include the Salesforce MyDomain or sandbox URL in its Subject Alternative Names.
  • The Sandbox checkbox in the Salesforce connection settings is not correctly toggled.

• Resolution:

  • Inspect the certificate's SAN entries using OpenSSL: openssl x509 -in cert.crt -text -noout. Confirm the Subject Alternative Name section includes your Salesforce MyDomain URL.
  • In the Salesforce connection settings in Studio, verify the Sandbox checkbox is correctly set for your target org.
  • If the Salesforce URL is absent from the SANs, regenerate the certificate to include the specific domain.
  • If the same connection succeeds on a cloud agent group but fails on a private agent, the cause may instead be a missing SNI extension in the agent's TLS handshake. See Salesforce sandbox connection fails with certificate mismatch.

Error de conexión a la base de datos del agente privado (TranDb)

• Síntoma: Las operaciones fallan con errores que hacen referencia a la base de datos PostgreSQL interna del agente privado (TranDb), por ejemplo Failed to connect to back-end database 'TranDb' o FATAL: query_wait_timeout.
• Causa y resolución: Se trata de un problema a nivel de agente con las conexiones de base de datos internas del agente privado. Consulta Errores de conexión de TranDb en la guía de solución de problemas del agente para conocer las causas y la resolución.

El certificado de cliente no se carga en agentes privados de Linux

• Síntoma: Una operación que realiza una llamada de servicio web TLS mutua (certificado de cliente) saliente falla en tiempo de ejecución en un agente privado de Linux, con un error como:

  Problem with the local SSL certificate. Unable to set private key file: '<path>.key' type PEM.
  

  El certificado se carga correctamente en Studio, pero la operación falla cuando se ejecuta. La misma configuración puede haber funcionado anteriormente en un agente privado de Windows.

• Posibles causas:

  • El usuario del sistema operativo que ejecuta el agente de Jitterbit no tiene permiso de lectura para el archivo de clave privada o sus directorios principales.
  • Un módulo de seguridad de Linux como SELinux o AppArmor está bloqueando el acceso del agente al archivo de clave privada.

• Resolución:

  • Asegúrate de que la cuenta que ejecuta el agente de Jitterbit tenga acceso de lectura al archivo de clave privada y a todos los directorios principales.
  • Verifica si SELinux o AppArmor está restringiendo el acceso al archivo de clave y ajusta la política o el contexto del archivo según sea necesario.

Errores de transformación y datos

Elementos XML no compatibles (CDATA) incrustados en JSON

• Síntoma: Las secciones de datos de caracteres (CDATA) no son compatibles en XML incrustado dentro de JSON que se pasa a través de una transformación. Cuando están presentes, el siguiente error aparece en el registro de operaciones:

  Transformation failed. Error: The operation "Operation" failed.
  Error: Failed to convert XML file to JSON.
  org.jitterbit.integration.server.engine.EngineSessionException: org.xml.sax.SAXParseException ...
  

• Resolución: Utiliza un script de Jitterbit para Reemplazar los caracteres &, <, >, ' y " dentro de la sección CDATA, incluyendo los delimitadores CDATA (<![CDATA[ ... ]]>), con sus equivalentes escapados (&, <, >, ', "). Si no es viable dirigirse solo a la sección CDATA, se puede reemplazar toda la cadena XML que la contiene.

  El siguiente ejemplo se considera inválido sin estos reemplazos:

  {
    "name": "Jitterbit",
    "data": "<xml><content><![CDATA[<greeting>Hello, world!</greeting>]]></content></xml>"
  }
  

La transformación falla cuando un valor de cadena JSON excede la longitud máxima

• Síntoma: Una transformación que procesa un valor de cadena JSON grande falla con un error que indica que la cadena excede la longitud máxima permitida, por ejemplo:

  Transformation failed. Error: Error Code: String value length (20054016) exceeds the maximum allowed (20000000, from StreamReadConstraints.getMaxStringLength())
  

  El seguimiento de pila hace referencia a StreamConstraintsException y al analizador JSON del agente. Un desencadenante común es una respuesta de HTTP v2 con Obtener contenido de respuesta en cadena base64 habilitado: la codificación Base64 aumenta el contenido binario (como un archivo de audio o multimedia), por lo que la cadena codificada puede exceder el límite incluso cuando el archivo original es más pequeño.

• Causa: El analizador JSON del agente limita un valor de cadena JSON individual a 20 MB (20000000 caracteres) de forma predeterminada. Una respuesta o valor asignado más grande que esto falla mientras el agente lo analiza, antes de que se ejecute cualquier actividad posterior (como una carga).

• Resolución: En un agente privado que ejecuta la versión 12.5 o posterior, aumenta el límite con la clave MaxStringLength en la sección [JsonParser] del archivo de configuración jitterbit.conf (por ejemplo, establécela en 50000000 para un límite de 50 MB) y luego reinicia el agente. Esta clave está disponible en la versión 12.5 del agente y posteriores, así que actualiza el agente primero si está en una versión anterior.

Caracteres especiales en esquemas JSON proporcionados por conectores

• Síntoma: Cuando una transformación utiliza un esquema JSON heredado de una actividad de conector adyacente, cualquier carácter especial en un nombre de campo o nodo de esquema se reemplaza por guiones bajos (_). Al utilizar procesamiento JSON heredado (el predeterminado para proyectos creados antes de la versión 11.48 de Harmony), esto puede causar que el punto de conexión devuelva errores porque los nombres de campo reales ya no coinciden con lo que espera.

Por ejemplo, si la actividad proporciona un campo denominado location_ids[], se convierte a location_ids__. Si el endpoint aún espera el nombre original, puede devolver un error como:

"error_message": "{location_ids:expected String to be a Array}"

• Resolución:

  1. Confirma que se está utilizando un esquema JSON en la actividad afectada. Estos esquemas tienen un nodo raíz denominado json:

     

  2. Habilita la configuración de proyecto Preserve JSON names (requiere versión de agente 11.48 o posterior).

  3. Reconfigura, implementa y ejecuta la operación.

  Importante

  Cuando Preserve JSON names se habilita en un proyecto donde estaba deshabilitado anteriormente, el nuevo método de procesamiento se aplica solo a las operaciones y esquemas configurados después de habilitar la configuración. Las operaciones y esquemas existentes continúan utilizando el procesamiento JSON heredado. Para evitar inconsistencias dentro de un proyecto, reconfigura todas las operaciones y esquemas existentes después de habilitar esta configuración.

  Para verificar el nombre del campo que se envía al endpoint, consulta el valor jsonPropertyName en los datos de entrada o salida de la actividad con registro de depuración habilitado:

  

Los caracteres multibyte se corrompen en una respuesta grande del conector

• Síntoma: Un carácter multibyte en una respuesta del conector JSON se corrompe. El texto corrupto muestra el patrón clásico de bytes UTF-8 decodificados como Latin-1 (por ejemplo, São Luís devuelto como São LuÃs). Normalmente, solo se ve afectado un carácter multibyte que aparece después de aproximadamente los primeros 8 KB de la respuesta; el mismo carácter que aparece antes en la respuesta no se ve afectado.
• Posible causa: En las versiones de agente 12.8 y 12.9, la detección automática de codificación de caracteres solo muestrea el principio de la respuesta para determinar su codificación. Si esa muestra contiene solo caracteres ASCII, la respuesta se detecta como Latin-1 (ISO-8859-1) en lugar de UTF-8, lo que corrompe cualquier carácter multibyte que aparezca más allá de la porción muestreada.
• Resolución: Actualiza a la versión de agente 12.10 o posterior, que corrige la detección de codificación.

Esquemas reflejados con grupos de sustitución

• Síntoma: Los esquemas reflejados que utilizan grupos de sustitución XML no son compatibles. Usar uno genera un error en tiempo de ejecución:

  Failed to initialize transformation "<transformation name>". Failed to expand the (source|target) tree for the path: <path to substitution head node>.
  

  Este error también puede ocurrir por otras razones, como importar una asignación de transformación con nodos duplicados, y no necesariamente indica un problema de grupo de sustitución.

• Resolución: Si se confirma que los grupos de sustitución son la causa, borra el esquema reflejado y vuelve a crearlo utilizando un método diferente (carga, creación de esquema personalizado, etc.).

La importación de una asignación de transformación con nodos duplicados falla con "node cannot be created"

• Síntoma: Una transformación cuya asignación fue importada desde un archivo que hace referencia a nodos duplicados falla en tiempo de ejecución con un error como:

Error al inicializar la transformación "<nombre de transformación>". Error al expandir el árbol de destino para la ruta: <ruta al nodo>. No se puede crear el nodo: <nombre del nodo>.

La asignación puede parecer correcta en el diseñador de transformaciones aunque la operación falle al ejecutarse.

• Posible causa: Importar un archivo de asignación que agregó nodos duplicados al esquema de destino no aplicó el cambio correspondiente a la definición del esquema utilizada cuando se ejecuta la operación, dejando los dos fuera de sincronización. Esto se ha corregido, pero una transformación cuya asignación se importó antes de la corrección aún puede verse afectada.

• Solución: En la transformación afectada, usa Eliminar todas las asignaciones bajo este nodo en el nodo raíz para eliminar todas las asignaciones, luego importa el archivo de asignación nuevamente. Reimportar resincroniza la definición del esquema utilizada en tiempo de ejecución con la asignación. Si el error persiste, reconfigura la actividad que proporciona el esquema, luego actualiza el esquema en la transformación.

Reprocesamiento de esquema XML reflejado en proyectos creados antes de la versión 10.25

• Síntoma: Debido a cambios en las versiones de Harmony 10.25 y 10.27, los proyectos creados antes de 10.25 que utilizan esquemas XML reflejados pueden comportarse de manera diferente a la esperada. Las asignaciones que utilizaban funciones XML que involucran espacios de nombres (como SelectNodes) ahora pueden no ser válidas.

  La diferencia está en el manejo del prefijo de espacio de nombres:

  • Antes de 10.25: Los esquemas XML reflejados utilizaban el prefijo de espacio de nombres predeterminado xsi.
  • 10.25 y posterior: Los esquemas XML reflejados utilizan el prefijo de espacio de nombres calificado ns. Los campos sin asignar no se muestran en el esquema.

• Solución: A partir de la versión 10.27, importar un proyecto cuyos esquemas XML reflejados se crearon antes de 10.25 conserva el prefijo de espacio de nombres original, por lo que el esquema es idéntico al momento de su creación. Para forzar una actualización al prefijo de espacio de nombres actual, regenera el esquema actualizándolo o reconfigurando la actividad que lo proporciona. Después de regenerar, revisa todas las llamadas de función de espacio de nombres XML afectadas y actualiza las referencias de prefijo en consecuencia.

  Consulta la comparación de esquema XML anotado para ver una ilustración de la diferencia entre los dos formatos.

Advertencia de subelemento adicional en registros de operación

• Síntoma: Un mensaje de subelemento adicional en los registros de operación es una advertencia, no un error, y generalmente se puede ignorar. Indica que la carga útil de la API de un conector devolvió más nodos o campos de los definidos en el esquema de datos de respuesta.
• Solución: Si necesitas capturar los datos adicionales, actualiza el esquema para incluir los campos adicionales.

Salida de transformación convertida a 0 para campos de destino con tipo de dato double

• Síntoma: Un campo de destino con tipo de dato double en el esquema recibe un valor de 0 aunque el script de mapeo devuelve un valor de cadena no vacío.
• Posible causa: Cuando la transformación procesa una salida de script, convierte el resultado al tipo de dato del campo de destino. Si el valor de cadena comienza con un carácter que no es un dígito (por ejemplo, "string1"), no se puede extraer ninguna porción numérica y el campo recibe el valor numérico predeterminado de 0. Por el contrario, un valor como "1string" produciría 1, ya que el dígito inicial se mantiene.
• Resolución:
  1. Verifica la definición del esquema para el campo de destino afectado y confirma si su tipo de dato es double u otro tipo de dato numérico.
  2. Si el script de mapeo puede devolver una cadena no numérica, añade validación explícita para asegurar que solo valores numéricos se asignen a campos de destino numéricos, o cambia el tipo de dato del campo en el esquema.

Campos mapeados en blanco con esquemas de origen planos

• Síntoma: Los campos de destino aparecen en blanco en la salida de la operación aunque los datos de origen contienen valores. Este problema ocurre específicamente al usar un esquema de origen plano. No ocurre con esquemas reflejados o esquemas JSON.
• Posible causa: El modo de transformación de streaming predeterminado procesa registros de forma incremental, lo que puede causar que los campos mapeados no reciban valores cuando se usan con esquemas de origen planos.

• Resolución:

  1. Añade un paso de script al inicio de la operación que desactiva las transformaciones de streaming estableciendo jitterbit.transformation.auto_streaming en false:

     $jitterbit.transformation.auto_streaming = false;
     

  2. Implementa y vuelve a ejecutar la operación. Para más contexto sobre el streaming y el procesamiento de transformaciones, consulta Procesamiento de transformaciones.

Nodo de bucle de destino mapeado a múltiples nodos de bucle de origen

• Síntoma: Una transformación no es válida o falla al implementarse con:

  Mappings of a target loop node depend on more than one source loop node.
  

• Posible causa: Un nodo de bucle de destino tiene asignaciones de campos que hacen referencia a dos o más nodos de bucle de origen diferentes. Cada nodo de bucle de destino solo puede iterar sobre un único nodo de bucle de origen.

• Resolución:
  1. Abre la transformación e identifica el nodo de bucle de destino señalado en el error.
  2. Revisa los mapeos bajo ese nodo para confirmar que todos los campos mapeados provienen del mismo nodo de bucle de origen.
  3. Si se necesitan datos de múltiples nodos de origen, preprocesa o fusiona los datos de origen adicionales en un paso de script antes de la transformación, de modo que un único nodo de origen unificado alimente el bucle de destino.
  4. Para más detalles sobre patrones de mapeo válidos, consulta Validez del mapeo de transformaciones.

La transformación descarta registros duplicados cuando la salida es jerárquica

• Síntoma: Una transformación que lee un origen CSV y asigna a un formato de salida jerárquico (como JSON) descarta silenciosamente registros duplicados. Los registros con valores de campo idénticos aparecen solo una vez en la salida sin importar cuántas veces ocurran en el origen. La operación se completa exitosamente pero reporta menos registros de destino que registros de origen.
• Posibles causas:
  • Al convertir datos de origen planos a un formato de salida jerárquico, el motor de transformación elimina registros duplicados durante la normalización. Los registros con valores idénticos después del análisis se tratan como duplicados y solo se mantiene una copia.
  • Este comportamiento es específico de la salida jerárquica. Cuando el esquema de salida es plano, la normalización no se ejecuta y se escriben todos los registros.
  • El motor de transformación también recorta espacios en blanco al inicio y final de los valores de campos CSV de forma predeterminada. Los registros que difieren solo por espacios al inicio o final se vuelven idénticos después del recorte y están sujetos a la misma deduplicación.
• Resolución:
  • Activa la fragmentación en las opciones de operación. La fragmentación procesa registros en lotes, lo que evita la normalización y preserva todos los registros incluyendo duplicados.
  • Usa un esquema de salida plano en la transformación en lugar de uno jerárquico. La normalización no se aplica a la salida plana, por lo que se preservan todos los registros.
  • Desactiva la normalización estableciendo una variable de Jitterbit en un paso de script anterior a la transformación. Para transformaciones plano a plano, establece jitterbit.transformation.disable_normalization en true. Para transformaciones plano a XML, establece jitterbit.transformation.flat_to_xml.disable_normalization en true (requiere agente 11.58 o posterior). Ambas variables pueden afectar otras transformaciones en la misma operación, así que prueba el cambio cuidadosamente.
  • Si los duplicados son causados específicamente por diferencias de espacios en blanco, establece jitterbit.source.preserve_char_whitespace en true en un paso de script anterior a la transformación. Esto preserva espacios en blanco durante el análisis para que los registros afectados permanezcan distintos.

Los IDs numéricos largos se corrompen en la salida de transformación

• Síntoma: Un valor numérico largo (por ejemplo, un número de seguimiento, número de cuenta o ID externo) se envía al destino con un valor incorrecto. El número es demasiado grande para caber en el tipo numérico implícito utilizado durante la asignación, por lo que se desborda y produce un valor incorrecto en el destino.
• Causa posible: El campo de origen o destino está implícitamente tipado como un tipo de dato numérico cuyo rango no puede contener el valor completo, causando un desbordamiento durante la conversión.
• Resolución:
  • En la transformación, establece el tipo de dato del campo de destino afectado como String en lugar de un tipo numérico. Los IDs largos que no se utilizan en operaciones aritméticas deben tratarse como cadenas de texto.

  • Si el campo de origen también está tipado numéricamente, convierte explícitamente el valor con String antes de asignarlo:

    String($source.numericId)
    

La salida de transformación JSON omite campos null y de cadena vacía

• Síntoma: Una transformación JSON elimina campos cuyo valor es null o una cadena vacía ("") de la carga útil de salida, aunque esos campos estén explícitamente asignados. El sistema de destino recibe una carga útil que no incluye los campos omitidos, lo que puede causar errores de validación posteriores cuando el destino requiere que los campos estén presentes.
• Causa posible: El procesador de salida JSON omite campos con valores null o de cadena vacía de forma predeterminada.
• Resolución:
  • En un paso de script anterior a la transformación, establece jitterbit.target.xml.include_nil_attribute en true. En la versión del agente 11.37 o posterior, esto incluye valores null y cadenas vacías en la salida JSON, coincidiendo con la entrada. (A pesar del xml en su nombre, esta variable se aplica a destinos JSON).
  • Si necesitas control total sobre qué campos aparecen en la carga útil, construye el cuerpo JSON en un paso de script usando concatenación de cadenas y envíalo a través de un conector HTTP v2 con un cuerpo de solicitud sin esquema.

Los campos asignados vacíos se convierten en xsi:nil="true" e invalidan una solicitud XML o SOAP

• Síntoma: En una transformación XML o SOAP, un campo asignado con un valor vacío se emite como un elemento nil, y el punto de conexión de destino rechaza la solicitud. Por ejemplo, una asignación de número de teléfono vacío produce:

  <ns1:Phone_Number xsi:nil="true"/>
  

  Algunos puntos de conexión (por ejemplo, servicios SOAP de Workday) lo tratan como inválido y devuelven un error.

• Causa: De forma predeterminada, cuando una asignación a un nodo de destino resulta en un valor nulo o vacío, la transformación incluye el nodo pero lo marca como nil (xsi:nil="true"). Esto se controla mediante jitterbit.target.xml.include_null_xml, cuyo valor predeterminado es true.

• Resolución: En un paso de script anterior a la transformación, establece $jitterbit.target.xml.include_null_xml = false para eliminar completamente de la salida los nodos con un valor nulo o vacío. Si en su lugar el nodo debe estar presente como un elemento vacío, utiliza las variables Jitterbit de destino relacionadas jitterbit.target.xml.include_empty_xml y jitterbit.target.xml.include_nil_attribute, que controlan si los valores vacíos y nulos se incluyen en la salida.

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

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

Errores de script y función

Funciones de archivo: La operación continúa después de un error en ArchiveFile o ReadFile

• Síntoma: Una operación se completa con un estado de éxito, pero los archivos no se archivaron o los datos no se leyeron como se esperaba. No aparece ningún error en el resultado de la operación, solo una advertencia en el registro de operaciones.
• Causa posible: ArchiveFile y ReadFile tienen comportamiento de fallo suave: si alguna de estas funciones falla, el script actual se cancela y se agrega una advertencia al registro de operaciones, pero la operación en sí no falla y los pasos posteriores continúan. A partir de la versión del agente 12.5, hay una excepción: ArchiveFile llamado con deleteSource establecido en true lanza un error capturable cuando no se puede eliminar el archivo de origen, en lugar de fallar silenciosamente.
• Resolución:
  • Revisa los registros de operaciones para buscar mensajes de advertencia cuando una operación se realiza correctamente pero falta la salida de archivo esperada.
  • Si el script debe detenerse en caso de un fallo de función de archivo, envuelve la llamada en una función Eval y llama a RaiseError explícitamente para promover la advertencia a un fallo de operación.

ReadFile: Lecturas parciales con contenido de archivo binario

• Síntoma: Un script que usa ReadFile para leer un archivo binario (como un ZIP o PDF) devuelve datos incompletos o corruptos.
• Causa posible: ReadFile no es confiable con contenido de archivo binario y típicamente lee solo una porción de tales archivos.
• Resolución: Usa Base64EncodeFile en lugar de ReadFile para leer el contenido completo de un archivo binario como una cadena codificada en Base64.

El contenido de ReadFile con bytes que no son UTF-8 falla cuando se asigna a una carga XML o JSON UTF-8

• Síntoma: Una transformación que asigna contenido de archivo sin procesar leído con ReadFile (por ejemplo, un archivo EDI sin procesar) a un campo de destino XML o JSON codificado en UTF-8 falla durante la conversión XML o JSON. Reemplazar el valor asignado con una cadena codificada permite que la operación se complete, lo que confirma que el contenido sin procesar es el desencadenante. Los intentos de eliminar el carácter ofensivo usando su punto de código Unicode (por ejemplo, Replace($readFile, HexToString("2026"), "~") para la elipsis U+2026) no coinciden, y llamar a StringToHex en el contenido con soporte Unicode habilitado genera:

  not a UTF-8 string, byte not in range: 13
  

• Causa: El contenido del archivo contiene un byte que no es UTF-8 válido (por ejemplo, el byte único 0x85, que algunos archivos EDI usan como terminador de segmento). Este byte sin procesar no es lo mismo que la codificación UTF-8 de varios bytes de un carácter Unicode de aspecto similar (la elipsis U+2026 se codifica como tres bytes), por lo que un reemplazo dirigido al punto de código Unicode nunca coincide. Con jitterbit.scripting.hex.enable_unicode_support establecido en true, las funciones hex interpretan el contenido como UTF-8 y fallan en el byte inválido.

• Resolución: Coincide y reemplaza el byte sin procesar con el soporte Unicode hex deshabilitado, de modo que HexToString funcione en bytes sin procesar en lugar de caracteres UTF-8:

  $jitterbit.scripting.hex.enable_unicode_support = false;
  $badByte = HexToString("85");
  $readFile = Replace($readFile, $badByte, "~");
  

  Ajusta el valor hex (85) al byte reportado por StringToHex($readFile), y la cadena de reemplazo (~) según sea necesario, luego asigna el valor sanitizado.

FlushFile / FlushAllFiles: Error cuando el archivo de destino ya existe

• Síntoma: Un script falla al intentar escribir un archivo en un destino que ya contiene un archivo con el mismo nombre.
• Posible causa: FlushFile y FlushAllFiles (y por extensión ArchiveFile) generan un error si un archivo con el nombre de destino ya existe en el destino.
• Resolución:
  • Agrega una llamada a DeleteFile o DeleteFiles antes de la operación de escritura para eliminar el archivo existente.
  • Alternativamente, usa un nombre de archivo dinámico que incluya una marca de tiempo o un identificador único para evitar colisiones.

DeleteFiles: Error cuando no se puede encontrar la ruta de origen

• Síntoma: Un script que usa DeleteFiles falla con un error cuando no se puede encontrar la ruta de origen o el directorio especificado. (Un filtro que no coincide con ningún archivo devuelve 0 en lugar de un error.)
• Posible causa: Si no se puede encontrar la ruta de origen, DeleteFiles genera un error en lugar de devolver silenciosamente. Esto puede causar fallos inesperados de operación cuando el archivo a eliminar no existe.
• Resolución: Envuelve la llamada a DeleteFiles en una función Eval para capturar el error y manejarlo sin fallar la operación.

GetJSONString: Ejecución interrumpida en ruta inválida

• Síntoma: Un script que llama a GetJSONString falla cuando la ruta proporcionada no se resuelve en el JSON (por ejemplo, el nodo está ausente o una matriz está vacía). El error es genérico y no identifica la ruta como la causa; cuando la operación se invoca a través de una API, puede aparecer como un Proxy Error [502] engañoso devuelto a quien llama la API.
• Causa posible: Si el argumento path pasado a GetJSONString es inválido o no coincide con ningún dato, la función interrumpe el flujo de ejecución inmediatamente y devuelve un error, lo que puede causar que todo el script se cancele.
• Resolución:
  • Valida la ruta JSON antes de pasarla a GetJSONString, o (en versión de agente 11.59 / 12.3 o posterior) usa GetJSONStringEx, que devuelve un valor personalizable en lugar de interrumpir la ejecución cuando la ruta es inválida o no se encuentra.
  • Registra la carga útil JSON inmediatamente antes de la llamada a GetJSONString para verificar la estructura real y confirmar la ruta.

Se excedió el límite de iteraciones del bucle de script

• Síntoma: Un script falla con un error que indica que se ha alcanzado el número máximo de iteraciones del bucle. El límite predeterminado es 50,000 iteraciones.
• Causas posibles:
  • Un bucle en un script de Jitterbit excede el límite de iteraciones de la plataforma.
  • Un script de JavaScript contiene múltiples bucles cuyo número combinado de iteraciones excede 50,000. En JavaScript, el límite se aplica por script (en todos los bucles), no por bucle individual.
• Resolución:
  • Revisa la lógica del script para determinar si el bucle se puede optimizar para reducir el número de iteraciones.
  • Para scripts de JavaScript en agentes privados, el límite por script se puede aumentar agregando JavaScriptMaxIterations=X (donde X es mayor que 50000) a la sección [Settings] del archivo de configuración del agente privado.
  • Para Jitterbit Script en agentes privados, aumenta el límite configurando jitterbit.scripting.while.max_iterations a un valor mayor que 50000.

Comparar una cadena con un número produce resultados inesperados

• Síntoma: Una comparación entre una cadena y un número devuelve un resultado inesperado. Por ejemplo, comparar una cadena no numérica con 0 se evalúa como igual, por lo que se ejecuta la rama incorrecta:

  $value = "test";
  If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
  // logs "equal", even though "test" is not 0
  

• Causa: Cuando los dos operandos son de tipos diferentes, Jitterbit Script convierte ambos a números para compararlos. Una cadena que no representa un número se convierte a 0, por lo que "test" == 0 se convierte en 0 == 0, que es true. Este es el comportamiento esperado.

• Resolución: Compara valores del mismo tipo. Para probar una cadena contra un valor específico, compárala con un literal de cadena (por ejemplo, $value == "0" o $value == "") en lugar de un número. Si un valor puede llegar como cualquiera de los dos tipos, convierte ambos operandos al mismo tipo (por ejemplo, con String) antes de comparar.

Unmap no desmapea un campo cuando se usa junto con RunScript

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

• Posibles causas:

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

• Resolución:

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

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

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

DBExecute: Error cuando auto_commit y transaction son ambos true

• Síntoma: Una operación que usa DBExecute falla con un error relacionado a configuraciones de transacción conflictivas.
• Posible causa: Tanto jitterbit.scripting.db.auto_commit como jitterbit.scripting.db.transaction están configuradas en true en el script antes de la llamada a DBExecute. Estas dos configuraciones son mutuamente excluyentes y combinarlas causa un error.
• Resolución: Decide si necesitas comportamiento de confirmación automática o control de transacciones explícito, luego configura solo la variable apropiada:
  • Para confirmación automática (cada sentencia se confirma inmediatamente): establece $jitterbit.scripting.db.auto_commit = true y deja jitterbit.scripting.db.transaction sin configurar o en false.
  • Para control de transacciones (confirmar al final de la transformación): establece $jitterbit.scripting.db.transaction = true y jitterbit.scripting.db.auto_commit = false.

CallStoredProcedure: resultSet siempre null con controladores ODBC

• Síntoma: Un script que usa CallStoredProcedure devuelve null para el parámetro resultSet aunque el procedimiento almacenado devuelve datos.
• Posible causa: El parámetro resultSet solo es compatible con controladores de base de datos JDBC. Cuando el endpoint de base de datos usa un controlador ODBC, resultSet siempre es null independientemente de lo que devuelva el procedimiento almacenado.
• Resolución:
  • Si se requiere el conjunto de resultados del procedimiento almacenado, cambia el endpoint de base de datos para usar un controlador JDBC en lugar de ODBC.
  • Si cambiar controladores no es posible, recupera datos de salida a través de parámetros de salida en lugar del argumento resultSet.

CallStoredProcedure: "Stored proc or function could not be found" con PostgreSQL JDBC

• Síntoma: Un script que utiliza CallStoredProcedure contra una base de datos PostgreSQL falla con:

  CallStoredProcedure failed to execute call "<function-name>".
  java.sql.SQLException: Stored proc or function could not be found: <function-name>
  

• Causa posible: El controlador JDBC de PostgreSQL distingue entre funciones y procedimientos. CallStoredProcedure siempre construye su llamada utilizando un patrón que el controlador interpreta como una búsqueda de un procedimiento. Si el objeto de la base de datos es una función de PostgreSQL en lugar de un procedimiento, el controlador no puede localizarlo y devuelve el error "no encontrado".

• Resolución:
  1. Determinar si el objeto de la base de datos que se está llamando es una función de PostgreSQL (devuelve un valor) o un procedimiento (sin valor de retorno).

  2. Reemplazar CallStoredProcedure con DBExecute y utilizar la sintaxis SQL correcta para el tipo de objeto:

     • Función: utilizar SELECT.

       $result = DBExecute("<TAG>Sources/My DB Connection</TAG>", "SELECT my_function(arg1, arg2)");
       

       DBExecute devuelve un conjunto de resultados. Utilizar un bucle While con Get para leer los valores devueltos.

     • Procedimiento: utilizar CALL.

       DBExecute("<TAG>Sources/My DB Connection</TAG>", "CALL my_procedure(arg1, arg2)");
       

       Los procedimientos de PostgreSQL no devuelven un valor; el valor de retorno de DBExecute puede descartarse.

DBLoad: Requiere un controlador de base de datos JDBC

• Síntoma: Una operación que utiliza DBLoad falla o no produce salida cuando el punto de conexión de la base de datos utiliza un controlador ODBC.
• Causa posible: DBLoad solo funciona con puntos de conexión de base de datos configurados para utilizar un controlador JDBC. No es compatible con controladores ODBC.
• Resolución: Confirmar que el punto de conexión de la base de datos asociado a la actividad de destino utiliza un controlador JDBC. Si utiliza un controlador ODBC, cambiar a JDBC.

AESDecryption falla con datos cifrados bajo OpenSSL 3

• Síntoma: Una operación que utiliza AESDecryption falla o devuelve salida distorsionada al descifrar datos que fueron cifrados utilizando OpenSSL 3.
• Causa posible: AESDecryption utiliza un algoritmo AES heredado de forma predeterminada que no es compatible con el cifrado de OpenSSL 3. Cuando los datos cifrados se produjeron con OpenSSL 3, el descifrado falla sin configuración adicional.
• Resolución:
  • Para agentes privados versión 11.42 o posterior, establecer jitterbit.scripting.aes.default en true en un paso de script anterior a la llamada de AESDecryption para habilitar la compatibilidad con OpenSSL 3.
  • Alternativamente, reemplazar AESDecryption con AESDecryptionEx, que es compatible con OpenSSL 3 de forma predeterminada en versiones de agente 11.42 o posterior.

Las variables del proyecto devuelven valores vacíos durante pruebas de scripts y transformaciones

• Síntoma: Al probar un paso de script o transformación en Studio, una variable de proyecto referenciada en el script o mapeo devuelve un valor vacío en lugar del valor configurado. La prueba puede fallar con un error no relacionado con la variable misma (por ejemplo, un tiempo de espera de conexión causado por una dirección de servidor en blanco).
• Causa posible: Los valores de las variables de proyecto se inyectan en tiempo de ejecución por la plataforma Harmony. Durante una prueba en tiempo de diseño, no existe contexto de tiempo de ejecución para inyectar ese valor, por lo que una referencia de variable de proyecto devuelve un valor vacío a menos que la variable tenga un Valor predeterminado configurado para usar como respaldo.
• Resolución:
  • Establecer un valor predeterminado en la variable de proyecto: En la configuración de la variable de proyecto, ingresa el valor a usar durante las pruebas en el campo Valor predeterminado. Esta es la solución más simple para un valor configurado estático. Ten en cuenta que el valor predeterminado se usa siempre que la variable no se haya establecido en tiempo de ejecución (no solo durante pruebas en tiempo de diseño), por lo que en tiempo de ejecución también actúa como respaldo cuando la variable no está establecida. Consulta Variables de proyecto para obtener detalles de configuración.
  • Usar una variable global: Reemplaza la referencia de variable de proyecto con una variable global y asigna su valor dentro del script mismo, antes de la línea que la usa. Dado que una variable global obtiene su valor de la ejecución del script en lugar de la inyección en tiempo de ejecución, asignarla antes de su uso la hace disponible durante una prueba en tiempo de diseño. Prefiere esto cuando el valor se deriva en un script, o cuando no deseas un valor de respaldo en tiempo de ejecución. Consulta Variables globales para obtener detalles. Si la variable global se referencia en un campo de configuración de conector en lugar de directamente en un script, también debes definir un valor predeterminado por campo para ese campo (consulta Definir un valor predeterminado, que cubre tanto el método de píldora de variable como el método de sintaxis en línea para campos que no muestran una píldora).

IsNull devuelve false para cadenas vacías de datos de origen JSON

• Síntoma: IsNull devuelve false para un campo asignado desde un origen JSON, incluso cuando el campo parece no tener valor. La lógica descendente que depende de la verificación nula se comporta de manera inesperada o produce resultados incorrectos.
• Causa posible: JSON distingue entre un valor ausente o explícitamente null y una cadena vacía (""). Un campo establecido en "" en JSON es una cadena vacía, no nulo, por lo que IsNull correctamente devuelve false para él. A partir del agente 11.37, el agente preserva esta distinción con precisión. Los scripts o transformaciones que anteriormente dependían de que IsNull devolviera true para cadenas vacías dependían de un comportamiento anterior que ya no es correcto.

• Resolución:

  • Usar IfEmpty para manejar tanto null como cadenas vacías: La función IfEmpty devuelve un valor predeterminado cuando el argumento es nulo o una cadena vacía, y es el reemplazo recomendado para este escenario:

    // Devuelve "default" si el campo es null o una cadena vacía
    result = IfEmpty($myField, "default");
    

  • Usar Length para probar cadenas vacías explícitamente: Si solo necesitas verificar si una cadena está vacía (no nula), usa Length($myField) == 0.

  • Corregir los datos de origen: Si el origen JSON debe indicar que no hay valor, actualízalo para enviar "field": null u omite el campo completamente en lugar de "field": "".

Comparar una variable de cadena con el número 0 devuelve inesperadamente true

• Síntoma: Una comparación como $myVar == 0 devuelve true incluso cuando $myVar contiene una cadena no numérica (por ejemplo, "test"). Las condiciones If y otra lógica que verifica cero producen resultados inesperados.
• Causa posible: Cuando Jitterbit Script compara valores de diferentes tipos de datos, intenta convertir ambos operandos a doubles como paso final. Cuando se aplica a una cadena no numérica, la conversión falla y devuelve 0 como valor predeterminado. La comparación entonces se evalúa como 0 == 0, que es true.
• Resolución:
  • Asegúrate de que ambos lados de la comparación usen el mismo tipo de datos. Si la intención es verificar si una variable de cadena contiene el valor "0", compara contra el literal de cadena "0" en lugar del entero 0:

// Compares string to integer: non-numeric strings coerce to 0 and match unexpectedly
        If($myVar == 0, ...)

        // Compares string to string: behaves as expected
        If($myVar == "0", ...)

• Si se espera que la variable contenga un valor numérico, asegúrate de asignarlo como número en lugar de una cadena antes de la comparación.

La aritmética decimal produce resultados inesperados de punto flotante

• Síntoma: Una expresión aritmética que involucra literales decimales produce un resultado ligeramente diferente del valor esperado. Por ejemplo, Double(12.01) - Double(12.00) devuelve 0.00999999999999979 en lugar de 0.01, y (4.9 * 100) - 490 se evalúa como 5.6843418860808e-14 en lugar de 0.
• Causa posible: Jitterbit Script almacena números como valores de punto flotante. La mayoría de las fracciones decimales no se pueden representar exactamente en punto flotante binario, por lo que la aritmética en ellas puede acumular pequeños errores de redondeo. La resta que cancela la mayoría de un valor expone este residuo. Convertir explícitamente valores como Double no lo previene: especifica el tipo de dato pero no cambia cómo se almacena o se calcula el valor.

• Resolución:

  • Aplicar Round al resultado: Usa Round con la cantidad de decimales requerida para el cálculo:

    $a = Round(Double(12.01) - Double(12.00), 2); // returns 0.01
    

  • Convertir literales decimales usando Float: Envuelve el literal decimal en Float antes del cálculo:

    $a = (Float(4.9) * 100) - 490;
    WriteToOperationLog($a);
    

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

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

El valor en caché expira antes de lo esperado

• Síntoma: Un valor escrito en el caché con una expiración larga (por ejemplo, 24 horas) desaparece mucho antes de que transcurra ese tiempo, o expira después de 30 minutos independientemente de lo que se haya establecido en WriteCache.
• Causa posible: Cada llamada a ReadCache reinicia la expiración del elemento en caché a 30 minutos (1800 segundos) a menos que se proporcione explícitamente el parámetro expirationSeconds. La expiración de WriteCache solo se aplica en el momento de la escritura; las lecturas posteriores sin una expiración explícita acortan silenciosamente la vida útil restante.
• Resolución:
  • Especificar la expiración en ReadCache: Pasa la cantidad deseada de segundos como parámetro expirationSeconds para preservar o extender la vida útil del valor en caché en cada lectura:

// Restablece la expiración a 24 horas en cada lectura
testVal = ReadCache("CacheTest", 86400, "env");

• Pasar -1 para preservar la expiración de escritura: Al pasar un valor no positivo, ReadCache retiene la expiración establecida por la llamada más reciente a WriteCache en lugar de aplicar una nueva:

  testVal = ReadCache("CacheTest", -1, "env");
  

RunXSLT falla con "XML version must be 1.0 or 1.1"

• Síntoma: RunXSLT falla con el error:

  Failed to execute xslt. XML version must be 1.0 or 1.1
  

  aunque el archivo XML de entrada contiene una declaración válida <?xml version="1.0"?>.

• Causa posible: La hoja de estilos XSLT está configurada para producir salida HTML (por ejemplo, <xsl:output method="html"/>). RunXSLT solo admite XML como salida. Cuando la hoja de estilos produce HTML, la función genera un resultado vacío, lo que desencadena este error. El mensaje de error se refiere a la declaración XML faltante en la salida (vacía), no en el XML de entrada.

• Resolución:

  • Actualizar XSLT para producir salida XML: Cambiar la declaración de salida de la hoja de estilos a <xsl:output method="xml"/>, o eliminar completamente la declaración xsl:output (XML es el valor predeterminado). Este es el enfoque recomendado y funciona tanto en agentes en la nube como en agentes privados.

  • Usar el plugin XSL Transform (solo agentes privados): Para grupos de agentes privados, el plugin XSL Transform deprecado utiliza el procesador XSLT Saxon y admite formatos de salida que no son XML, incluido HTML. Consulta Plugins disponibles para obtener detalles de instalación.

SelectSingleNode devuelve el nodo incorrecto cuando se usa con un elemento de matriz SelectNodes

• Síntoma: SelectSingleNode devuelve datos del elemento incorrecto (por ejemplo, siempre la primera coincidencia en el documento) cuando se llama en un elemento recuperado de una matriz SelectNodes.
• Causa posible: Usar una expresión XPath absoluta (una que comience con //) como argumento de ruta hace que SelectSingleNode busque desde la raíz del documento XML original en lugar de relativo al nodo actual. Una expresión como "//Item/ItemName" coincide con el primer ItemName en cualquier lugar del documento, independientemente de qué elemento Item se haya recuperado de la matriz.

• Resolución:

  • Usar una ruta relativa: Omitir el // inicial y especificar solo el nombre del elemento o una ruta relativa al nodo actual. Esto limita la búsqueda al nodo pasado como primer argumento:

    $itemName = SelectSingleNode($item, "ItemName");
    

  • Alternativa: envolver el nodo en String: Convertir el elemento de la matriz a una cadena antes de pasarlo a SelectSingleNode también produce el resultado correcto, aunque usar una ruta relativa es el enfoque preferido:

    $item = String($items[2]);
    $itemName = SelectSingleNode($item, "//Item/ItemName");
    

La salida de HexToBinary parece sin cambios cuando se registra

• Síntoma: HexToBinary parece no tener efecto: el valor escrito en el registro de operaciones se ve idéntico a la entrada hexadecimal, lo que sugiere que la conversión no ocurrió.
• Causa posible: WriteToOperationLog no puede generar datos binarios sin procesar. Cuando se le pasa un valor binario, lo convierte nuevamente a hexadecimal para su visualización. El mismo comportamiento se aplica en la ventana de prueba de script. La conversión funciona correctamente; solo la visualización se ve afectada.
• Resolución: Para trabajar con o verificar la salida binaria, escribirla en un archivo usando WriteFile. Por ejemplo:

WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/Write</TAG>", HexToBinary("1A3F"));

SortArray ordena nombres de archivo lexicográficamente, no cronológicamente

• Síntoma: SortArray devuelve nombres de archivo en orden alfabético en lugar del orden cronológico esperado cuando los nombres de archivo contienen cadenas de fecha u hora incrustadas.
• Causa posible: SortArray realiza una ordenación de cadena (lexicográfica). Para un nombre de archivo como ordall_DDMMYYHHMMSS.txt, la parte del día precede a la parte del año en la cadena, por lo que una ordenación alfabética no coincide con una ordenación basada en fechas.
• Resolución:
  • Si controlas la convención de nombres de archivo, cambia a un formato que se ordene correctamente cuando se ordene alfabéticamente, como YYYY-MM-DD_HHMMSS_filename.txt. Esta es la solución más simple y confiable.
  • Si el formato del nombre de archivo no puede cambiar, analiza la porción de fecha de cada nombre de archivo en una clave ordenable (por ejemplo, YYYYMMDDHHMMSS) y ordena según la clave analizada en lugar del nombre de archivo sin procesar.

URLEncode no codifica ciertos caracteres "seguros" o multibyte

• Síntoma: Un valor pasado a través de URLEncode se envía al destino con algunos caracteres sin codificar, lo que causa que el sistema receptor rechace la solicitud o malinterprete el valor. Esto afecta comúnmente a credenciales o valores de consulta que contienen caracteres como $, + o !.
• Causas posibles:
  • URLEncode sigue RFC 1738 y trata estos caracteres como "seguros", por lo que nunca los codifica: $ - _ . + ! * ' ( ) ,. Un destino que espera que estos caracteres se codifiquen con porcentaje recibe el carácter sin procesar en su lugar.
  • La compatibilidad con caracteres multibyte en URLEncode requiere la versión 12.4 del agente o posterior. En agentes anteriores, es posible que los caracteres multibyte no se codifiquen como se espera.

• Resolución:

  • Cuando los caracteres "seguros" deben codificarse (por ejemplo, en una contraseña OAuth o un valor que contiene +), utiliza la función encodeURIComponent de JavaScript en un paso de script de JavaScript en lugar de URLEncode:

    <javascript>
    $my_username = "$Example+User";
    $loginValue = encodeURIComponent($my_username);
    </javascript>
    

    Esto devuelve %24Example%2BUser.

  • Para codificar caracteres multibyte con URLEncode, confirma que el agente está en la versión 12.4 o posterior.

JavaScript: error "Call to Jitterbit Tomcat failed"

• Síntoma: Un paso de JavaScript complejo o de larga duración falla con un error genérico que hace referencia a Tomcat, aunque los servicios Jitterbit Apache y Jitterbit Tomcat en el agente se estén ejecutando. El script puede tener éxito cuando se reduce su complejidad (por ejemplo, al reducir los conteos de iteración o la profundidad de recursión).

  Call to Jitterbit Tomcat failed (null response). Make sure the Jitterbit Apache and Jitterbit Tomcat services are both running.
  Failed to execute script
  

• Causa posible: JavaScript recursivo profundo puede exceder el límite de profundidad de recursión del motor JavaScript del agente, produciendo un desbordamiento de pila que aparece como este error genérico de Tomcat. Este límite de recursión es intencional. El script típicamente se completa una vez que se reduce la profundidad de recursión.

• Resolución:
  • Reduce la profundidad de recursión o reescribe la lógica recursiva como un bucle iterativo.
  • Si el algoritmo no puede evitar recursión profunda, utiliza un enfoque que no dependa de ella.
  • Ten en cuenta que el límite de iteración de bucle por script separado (JavaScriptMaxIterations, consulta Límite de iteración de bucle de script excedido) no aumenta el techo de recursión, que no se expone como una configuración configurable.

JavaScript: Cambios de variables globales perdidos en caso de fallo de script

• Síntoma: Un script de JavaScript que modifica variables globales se ejecuta sin error aparente en algunos casos, pero los cambios en esas variables globales están ausentes en scripts u operaciones posteriores.
• Posibles causas:
  • En JavaScript, los cambios en variables globales solo se confirman cuando el script se completa exitosamente. Si el script falla en cualquier punto, todos los cambios de variables globales realizados durante esa ejecución se descartan.
  • Mezclar la sintaxis $variable con Jitterbit.SetVar/Jitterbit.GetVar para la misma variable dentro de un script de JavaScript puede causar un comportamiento impredecible en tiempo de ejecución.
• Resolución:
  • Estructura los scripts de JavaScript de modo que todas las asignaciones de variables globales ocurran después de la lógica que podría fallar, o utiliza manejo de errores para prevenir fallos a mitad del script.
  • Para cualquier variable en un script de JavaScript, utiliza ya sea la sintaxis $variable o Jitterbit.SetVar/Jitterbit.GetVar, nunca ambas. Elige una y úsala consistentemente en todo el script.
  • Para confirmar qué variables se están configurando, agrega llamadas a WriteToOperationLog para registrar los valores de las variables en puntos clave durante la ejecución.

JavaScript: GetVar devuelve null para variables de proyecto definidas por el usuario

• Síntoma: Llamar a Jitterbit.GetVar en una variable de proyecto definida por el usuario en un paso de script de JavaScript devuelve null en lugar del valor de la variable, sin mensaje de error.
• Posible causa: Jitterbit.GetVar y Jitterbit.SetVar están destinados a variables del sistema Jitterbit (por ejemplo, jitterbit.operation.name) y a nombres de variables que contienen un punto, que la notación de punto de JavaScript no puede referenciar directamente. No leen variables de proyecto ordinarias definidas por el usuario cuyos nombres no contienen un punto; pasar tal nombre a GetVar devuelve null. Referencia esas variables directamente con $name en su lugar. Estas funciones también convierten todos los valores a cadenas, por lo que no son adecuadas para matrices u objetos, y un valor establecido con SetVar puede leerse nuevamente con GetVar dentro del mismo script, pero no persiste en scripts posteriores.

• Resolución: Utiliza la sintaxis $variableName directamente en JavaScript para acceder a variables de proyecto y globales definidas por el usuario cuyos nombres no contienen un punto. Reserva GetVar y SetVar para variables del sistema Jitterbit y para variables cuyos nombres contienen un punto (por ejemplo, $hello.world), que la notación de punto de JavaScript no puede acceder directamente. Para una variable determinada, utiliza ya sea prefijo $ o GetVar/SetVar, no ambos. Consulta también JavaScript: Cambios de variables globales perdidos en caso de fallo de script.

  // Correct: access a user-defined project variable directly
  var value = $myProjectVar;
  
  // Incorrect for user-defined variables without periods:
  var value = Jitterbit.GetVar("$myProjectVar"); // returns null
  

Errores HTTP y API

504 Gateway Timeout

• Síntoma: Las llamadas a API a través de la puerta de enlace de API en la nube o privada devuelven 504 Gateway Timeout, típicamente después de la ventana de tiempo de espera de la puerta de enlace (30 a 180 segundos).
• Causa y resolución: La operación de respaldo está excediendo el tiempo de espera de la puerta de enlace de API, o la solicitud no puede asignarse a un agente disponible. Consulta HTTP 504 Gateway Timeout en la guía de solución de problemas de API Manager para conocer las causas completas y la resolución.

507 Insufficient Storage

• Síntoma: Una llamada a la API devuelve:

  507 Insufficient Storage
  

• Posibles causas:

  • El agente o el host de la puerta de enlace se ha quedado sin espacio en disco.
  • En una puerta de enlace de API privada, la puerta de enlace no puede abrir su archivo de carga útil o respuesta alojado y devuelve un 507 incluso cuando hay espacio en disco disponible. Esto generalmente indica un problema de registro de dominio privado o configuración de la puerta de enlace.

• Resolución:

  • Confirmar que el agente o el host de la puerta de enlace tiene suficiente espacio libre en disco.
  • Si el espacio en disco es suficiente y la API se sirve a través de una puerta de enlace de API privada, consulta La puerta de enlace privada devuelve HTTP 507 o "No such file or directory" para conocer la causa y la resolución.

502 Bad Gateway

• Síntoma: Una operación que utiliza Jitterbit Message Queue (JBMQ) falla con:

  502 Bad Gateway
  

  El servidor devolvió una respuesta inválida o incompleta.

• Posible causa: El servicio JBMQ no devolvió una respuesta completa a la solicitud, lo que produjo un 502. Este error es típicamente transitorio y puede no ser reproducible.

• Resolución:
  1. Reintentar la operación.
  2. Si el error persiste, contacta con soporte de Jitterbit.

Errores en tiempo de diseño

Estos problemas aparecen mientras se construye, valida o implementa un proyecto en Studio, en lugar de cuando se ejecuta una operación.

Errores comunes de validación de operaciones

Las operaciones con errores de validación muestran un icono inválido en el lienzo de diseño y en el panel de proyecto. Haz clic en el icono para ver el mensaje de error específico.

La siguiente tabla enumera los errores de validación comunes y sus resoluciones:

Errores de regla de validación HTTP

Una de las reglas de validación HTTP se aplica a operaciones que utilizan el patrón de archivo de dos destinos donde una actividad HTTP en la posición Destino 1 escribe una respuesta a una segunda actividad de destino (Destino 2). En este escenario, la regla de validación requiere que una actividad HTTP Destino 1 no se utilice en ninguna otra operación del patrón de archivo de dos destinos donde la actividad HTTP Destino 1 escriba a una segunda actividad de destino diferente.

Las operaciones que violan esta regla de validación aparecen como inválidas con un mensaje de error similar al siguiente ejemplo:

Resolver errores de validación HTTP

Sigue las instrucciones en el mensaje de error para corregir las operaciones y que sean válidas. Para resolver estos errores, completa los siguientes pasos:

1. Duplica la actividad de destino HTTP en la posición Destino 1 de una de las operaciones que utiliza el patrón de archivo HTTP de dos destinos.

2. Reemplaza la actividad de destino HTTP en la posición Destino 1 de las operaciones identificadas con la copia duplicada.

3. Repite para cualquier operación inválida adicional. Después de resolver los errores de validación, vuelve a implementar las operaciones.

Desactivar la regla de validación HTTP

En ciertas situaciones, es posible que desees desactivar esta regla de validación HTTP. Para desactivar la regla, completa los siguientes pasos:

1. Abre la configuración del proyecto:

   

2. En la pestaña Implementar, desactiva Regla de validación HTTP:

   

3. Haz clic en Guardar.

Después de desactivar y guardar la configuración, los errores de validación de operación de esta regla deberían resolverse. Sin embargo, cualquier actividad HTTP Destino 1 utilizada en una operación del patrón de archivo de dos destinos escribe a la actividad Destino 2 de la última operación implementada. Este comportamiento podría causar que se escriban datos inválidos.

Reactivar la regla de validación HTTP

Si previamente desactivaste la regla de validación HTTP y deseas reactivarla, completa los siguientes pasos:

1. Abre la configuración del proyecto.

2. En la pestaña Implementar, activa Regla de validación HTTP.

3. Haz clic en Guardar. Este cambio es un cambio en tiempo de diseño y no implementa ningún cambio en la nube de Harmony.

4. Resuelve cualquier error de validación HTTP (consulta Resuelve errores de validación HTTP).

5. Redeploy the project (consulta Implementación de proyectos).

   Nota

   Antes de la reimplementación, Harmony permite la ejecución de cualquier operación ahora inválida porque Harmony ejecuta las operaciones actualmente implementadas. Se requiere la reimplementación de las operaciones afectadas para que los cambios se propaguen a Harmony.

Los nombres de componentes deben ser únicos después de importar un proyecto

• Síntoma: Después de importar un proyecto desde un archivo de exportación JSON, uno o más componentes se muestran como inválidos y la implementación falla con un mensaje similar a:

  [Operation / Connection / Activity / Transformation / Script / Tool / Email / Variable] names must be unique.
  

• Causa posible: El proyecto importado contiene múltiples componentes del mismo tipo con nombres idénticos. Studio evita crear nombres duplicados al configurar componentes directamente en la interfaz de usuario, pero una importación de proyecto completa no aplica esa verificación.

• Resolución:
  1. En el panel de proyectos, identifica los componentes inválidos, que se muestran en cursiva roja con un icono de error .
  2. Haz clic en el icono de error para ver el nombre duplicado específico que causa el conflicto.
  3. Cambia el nombre de uno de los componentes duplicados para que cada nombre sea único dentro de su tipo.
  4. Reimplementa el proyecto después de resolver todos los errores de nombres duplicados.
  5. Para traer solo componentes seleccionados a un proyecto existente, utiliza importación selectiva, que marca conflictos con componentes del mismo nombre ya presentes en el proyecto destino y te permite reemplazarlos o mantener ambos.

El conector solo para agentes privados bloquea la importación a un entorno de agente en la nube

• Síntoma: La importación o migración de un proyecto a un entorno asociado con un grupo de agentes en la nube se bloquea porque el proyecto utiliza un conector solo para agentes privados. El mensaje enumera los conectores solo para agentes privados responsables. Una importación de proyecto completa muestra:

  The project you are importing uses private agent only connectors and cannot be imported into a cloud environment.
  

  Una importación selectiva muestra un diálogo Component import not allowed:

  The components you are importing uses private agent only connectors and cannot be imported into a cloud environment.
  

• Causa posible: El proyecto utiliza uno o más conectores que están disponibles solo en agentes privados. La columna Agent availability en la lista de conectores muestra cuáles son conectores solo para agentes privados. Los agentes en la nube no admiten estos conectores, por lo que Studio evita que el proyecto se importe o migre a un entorno de agente en la nube.

• Resolución:
  • Importa o migra el proyecto a un entorno asociado con un grupo de agentes privados que tenga el conector requerido instalado.
  • Si el proyecto debe ejecutarse en agentes en la nube, reemplaza las actividades de conector solo para agentes privados con conectores compatibles con la nube (como HTTP v2 para API REST, o el conector de base de datos con un endpoint accesible desde la nube) antes de importar.

Cargar un archivo de esquema lo reemplaza en todo el proyecto

• Síntoma: Después de cargar un nuevo archivo de esquema durante la configuración de transformación, otras transformaciones en el proyecto que usaban el mismo esquema ahora se comportan de manera inesperada o producen errores.
• Causa posible: Cuando se carga un archivo con el mismo nombre que un archivo de esquema existente ya definido en el proyecto, Studio muestra un diálogo ¿Sobrescribir archivo?. Si haces clic en Continuar, el archivo existente se reemplaza en todas las ubicaciones donde se usa. Este reemplazo es a nivel de proyecto, no limitado a la transformación actual.
• Resolución:
  1. Antes de cargar un archivo de esquema de reemplazo, confirma si el esquema existente se comparte: abre el esquema para editarlo y, si más de un componente lo referencia, Studio muestra un diálogo Esquema utilizado por múltiples componentes que los enumera (consulta Actualizar esquemas definidos por transformación). Evalúa el impacto en todos los componentes enumerados antes de continuar.
  2. Si solo una transformación debe usar el esquema actualizado, haz clic en Cancelar en el diálogo ¿Sobrescribir archivo? (o cambia el nombre del nuevo archivo antes de cargarlo) para que no sobrescriba el archivo compartido.

La implementación de la plantilla de proceso de Marketplace falla debido a una falta de coincidencia de esquema

• Síntoma: Un proyecto importado de una plantilla de proceso de Marketplace falla al implementarse o produce errores en tiempo de ejecución porque faltan campos en una transformación o la validación de actividad de origen y destino falla.
• Causa posible: Las plantillas de proceso se desarrollan contra una instancia de punto de conexión específica. Si tu instancia es diferente (por ejemplo, si tu organización de Salesforce o NetSuite tiene campos personalizados o estándar diferentes), los esquemas incrustados en las transformaciones de la plantilla pueden no coincidir con tu punto de conexión.
• Resolución:
  1. En la transformación afectada, abre la configuración de esquema y haz clic en el icono de actualización (o la palabra Actualizar) para regenerar el esquema desde tu punto de conexión conectado.
  2. Si el esquema aún no coincide después de actualizar, borra el esquema existente y vuelve a reflejarlo desde un archivo de muestra actual o directamente desde el punto de conexión.
  3. Reasigna los campos que se agregaron o eliminaron durante la regeneración del esquema.
  4. Reimplementa el proyecto y vuelve a ejecutar la operación para confirmar que el problema se resolvió.

Studio se vuelve lento o no responde con proyectos muy grandes

• Síntoma: Studio responde lentamente cuando un único flujo de trabajo contiene un número muy grande de operaciones, o cuando se guarda un script muy grande.
• Causa posible: El lienzo de diseño renderiza todas las operaciones en el flujo de trabajo activo a la vez, por lo que un flujo de trabajo con un número muy grande de operaciones exige mucha memoria del navegador.
• Resolución:
  • Divide los flujos de trabajo grandes en subflujos de trabajo más pequeños y vinculados. Studio renderiza solo el lienzo del flujo de trabajo activo, por lo que menos operaciones por flujo de trabajo mejora la capacidad de respuesta. Usa acciones de operación para encadenar subflujos de trabajo.
  • Si la lentitud ocurre específicamente al guardar un script grande, divide el script en scripts más pequeños y llámalos usando RunScript.

Errores de sistema y recursos

Fragmentación no respetada cuando el origen es un conector basado en SDK

• Síntoma: Una operación con fragmentación habilitada envía todos los registros al destino en un único lote en lugar de respetar el tamaño de fragmento configurado. Los errores del destino indican que se superó el límite de lote (por ejemplo, Salesforce devuelve EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call).
• Causa posible: La fragmentación no se admite cuando el origen es un conector basado en Connector SDK (como se indica en la columna Connector type de la lista de conectores). Las operaciones que utilizan orígenes que no son SDK, como HTTP, Database, Variable y Local Storage, respetan la fragmentación normalmente.
• Resolución:
  • Si la fragmentación no es necesaria, desactívala en las opciones de operación.
  • Si la fragmentación es necesaria, divide la operación en dos:
    • En la primera operación, lee desde el origen basado en SDK y escribe en una actividad Write de Variable.
    • En la segunda operación, lee desde una actividad Read de Variable y escribe en el destino original con fragmentación habilitada. Dado que el conector Variable no está basado en SDK, la fragmentación funciona correctamente en esta operación. Para los pasos de configuración de fragmentación, consulta Configurar fragmentación de operación.

Actualizaciones de variables perdidas en operaciones fragmentadas multihilo

• Síntoma: Cuando una operación se ejecuta con fragmentación habilitada y Max Number of Threads configurado a más de 1, las actualizaciones de variables globales o de proyecto realizadas durante la operación no se conservan completamente después de que se completa. Un caso posible es rellenar una variable de diccionario o matriz desde cada registro de origen y descubrir que contiene solo parte de los datos después (por ejemplo, aproximadamente la mitad de los registros cuando se ejecutan dos hilos). Esto puede ocurrir con conectores cuya configuración predeterminada utiliza más de un hilo, como actividades de Salesforce, que tienen 2 hilos de forma predeterminada.
• Causa posible: Cada hilo recibe su propia copia de las variables globales y de proyecto al inicio del procesamiento. Los cambios locales del hilo no se fusionan nuevamente en el estado compartido. Solo se conservan los cambios realizados por el primer hilo cuando se completa la operación; los cambios de todos los demás hilos se descartan.
• Resolución:
  • Si la corrección es más importante que el rendimiento por operación, establece Max Number of Threads en 1. Cada fragmento se procesa secuencialmente, por lo que las actualizaciones de variables no se dividen entre hilos.
  • Si se requiere rendimiento multihilo, no acumules estado por registro en una variable global o de proyecto. En su lugar, almacena la salida de cada hilo en un archivo Temporary Storage único o en una tabla de base de datos de almacenamiento provisional, luego consolida los resultados en una operación posterior de un solo hilo. Para un ejemplo práctico del patrón de almacenamiento provisional, consulta Alcance de variables con fragmentación.
  • De forma más general, no confíes en las actualizaciones de variables globales o de proyecto de operaciones fragmentadas multihilo en scripts u operaciones posteriores. Si el estado de la variable debe conservarse, establece esas variables en un paso de operación no fragmentado que se ejecute antes o después de la transformación fragmentada. Para obtener detalles sobre el comportamiento de fragmentación con variables, consulta Usar variables con fragmentación.

No se pudo crear el directorio temporal

• Síntoma: Una operación falla al crear un directorio temporal, con un error como:

  Failed to create the directory '/tmp/jitterbit/...'. Reason: boost::filesystem::create_directories: Permission denied
  

  En un grupo de agentes en la nube, puede reportar en su lugar No space left on device.

• Posibles causas:

  • En un agente privado, la cuenta de servicio del Agente Jitterbit carece de permisos a nivel del sistema operativo en la ruta de archivos temporales, o el disco está lleno.
  • En un grupo de agentes en la nube, la causa está del lado del agente administrado por Jitterbit en lugar de en tu proyecto o configuración.

• Resolución:

  • Para agentes privados, confirma que la cuenta de servicio del agente tiene permisos suficientes en la ruta de archivos temporales (/tmp o TemporaryFiles), y verifica que el host del agente tenga espacio en disco libre adecuado.
  • Para grupos de agentes en la nube, esto indica un problema del lado del agente que Jitterbit resuelve. Contacta al soporte de Jitterbit e incluye el mensaje de error y la hora en que ocurrieron las fallas.

Mensajes del registro de operación truncados aproximadamente en 100 KB

• Síntoma: Un mensaje del registro de operación aparece cortado, terminando con message truncated. Esto puede aparecer en los registros de operación o al ver una entrada de registro de Operación en la página Registros de API del Administrador de API.
• Posible causa: Los mensajes del registro de operación que exceden aproximadamente 100 KB (aproximadamente 99,000 caracteres) se truncan. El punto de truncamiento se marca con message truncated al final del mensaje.
• Resolución: Si necesitas el contenido completo del registro, reduce la verbosidad del registro de la operación o divide la operación en unidades más pequeñas que produzcan mensajes de registro más cortos.

El registro de depuración de operación expone información personal identificable y credenciales en texto plano

• Síntoma: Datos sensibles, credenciales o información personal identificable (PII) aparecen en los registros en la nube de Harmony.
• Posible causa: Cuando se habilita el registro de depuración de operación para una operación, todos los datos de solicitud y respuesta se almacenan en la nube de Harmony en texto plano durante 30 días.
• Resolución:
  • Utiliza el registro de depuración de operación solo en entornos controlados que no sean de producción o durante un período de diagnóstico limitado.
  • Para desabilitar la generación de datos de entrada y salida de componentes para un grupo de agentes privados, establece verbose.logging.enable=false en la sección [VerboseLogging] del archivo de configuración del agente.