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 conectores solo para agentes privados 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 requiere un conector nativo como origen
  • Actualizaciones de variables perdidas en operaciones multi-hilo fragmentadas
  • Error al crear directorio temporal
  • Mensajes del 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 falla 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 implementados en operaciones que se ejecutan en agentes privados, hacer clic en Test también asegura que se descargue la versión más reciente del conector al 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 conectores (solo agentes privados).
• Revisa los registros del agente (solo agentes privados).

Aislar fallas específicas del agente

Si una operación falla en algunos agentes pero tiene éxito en otros dentro del mismo grupo de agentes privados, usa la opción Run on dedicated agent para dirigir la operación a un agente específico. Esto te permite reproducir e investigar la falla 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 detectar 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 es saludable.
  • Los cambios implementados en un proyecto no se han sincronizado completamente con el agente.
  • El grupo de agentes está saturado de recursos. Un atraso de operaciones de larga duración o un uso sostenido alto de CPU o memoria puede 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 más detalles, consulta Zonas horarias de operación.
  • Para agentes privados, verifica que el agente esté en línea y sea saludable 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, verifica 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 errores de programación se correlacionan con la carga, reduce el número de operaciones de larga duración concurrentes. 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 se ejecuta una operación 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 (la herramienta Invoke Operation con Run type establecido en Asynchronously, o RunOperation llamado con runSynchronously establecido en false), la operación secundaria se ejecuta en un hilo separado y la principal continúa sin esperar. Las variables globales y los diccionarios se pasan a la secundaria por valor en lugar de por referencia y no son seguros para subprocesos, por lo que los cambios realizados en la secundaria no se reflejan en la principal. La principal también puede leer el valor antes de que la secundaria termine. Para el comportamiento equivalente en operaciones multi-hilo fragmentadas, consulta Variable updates lost in chunked multi-threaded operations.
• Resolución:
  • Si la operación principal depende de valores que produce la secundaria, invoca la secundaria de forma sincrónica (la herramienta Invoke Operation con Run type establecido en Synchronously, o RunOperation ejecutada de forma sincrónica, que es la opción predeterminada) para que la secundaria se complete y la 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 secundaria haya terminado; ejecuta la operación de forma sincrónica en su lugar.

Errores de conexión y autenticación

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

• Síntoma: Una conexión de Salesforce a un sandbox u organización con dominios mejorados habilitados falla con:

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

• Posibles causas:

  • El certificado no incluye la URL de MyDomain o sandbox de Salesforce en sus Nombres Alternativos del Sujeto.
  • La casilla Sandbox en la configuración de conexión de Salesforce no está activada correctamente.

• Resolución:

  • Inspecciona las entradas SAN del certificado usando OpenSSL: openssl x509 -in cert.crt -text -noout. Confirma que la sección Nombre Alternativo del Sujeto incluya tu URL de MyDomain de Salesforce.
  • En la configuración de conexión de Salesforce en Studio, verifica que la casilla Sandbox esté correctamente configurada para tu organización de destino.
  • Si la URL de Salesforce no está presente en los SAN, regenera el certificado para incluir el dominio específico.
  • Si la misma conexión funciona en un grupo de agentes en la nube pero falla en un agente privado, la causa podría ser una extensión SNI faltante en el protocolo de enlace TLS del agente. Consulta La conexión al sandbox de Salesforce falla con falta de coincidencia de certificado.

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.

• Causas posibles:

  • El usuario del sistema operativo que ejecuta el agente 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 se admiten en XML incrustado dentro de JSON que se pasa a través de una transformación. Cuando están presentes, aparece el siguiente error 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 posible 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 único valor de cadena JSON a 20 MB (20000000 caracteres) de forma predeterminada. Una respuesta o valor asignado mayor 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 en location_ids__. Si el punto de conexión 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 llamado 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 se habilita Preserve JSON names 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). Típicamente, solo un carácter multibyte que aparece después de aproximadamente los primeros 8 KB de la respuesta se ve afectado; el mismo carácter que aparece antes en la respuesta no se ve afectado.
• Causa posible: En las versiones de agente 12.8 y 12.9, la detección automática de codificación de caracteres solo muestrea el inicio 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, corrompiendo 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 recréalo 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 "no se puede crear el nodo"

• 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:

  Failed to initialize transformation "<transformation name>". Failed to expand the target tree for the path: <path to node>. The node: <node name> cannot be created.
  

El mapeo puede parecer correcto en el diseñador de transformaciones aunque la operación falle al ejecutarse.

• Posible causa: Importar un archivo de mapeo 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 desincronizados. Esto se ha corregido, pero una transformación cuyo mapeo se importó antes de la corrección aún puede verse afectada.

• Resolución: En la transformación afectada, usa Eliminar todos los mapeos bajo este nodo en el nodo raíz para eliminar todos los mapeos, luego importa el archivo de mapeo nuevamente. Reimportar resincroniza la definición del esquema utilizada en tiempo de ejecución con el mapeo. 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. Los mapeos que utilizaban funciones XML que involucran espacios de nombres (como SelectNodes) ahora pueden no ser válidos.

  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 mapear no se muestran en el esquema.

• Resolució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.
• Resolució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 devuelva 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, agrega 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.
• Causa posible: El modo de transformación de transmisión 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. Agrega un paso de script al inicio de la operación que desactiva las transformaciones de transmisión 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 la transmisión 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.
  

• Causa posible: 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 las asignaciones 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 asignación válidos, consulta Validez de asignación de transformaciones.

La transformación elimina 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) elimina 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.
• Causas posibles:
  • 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 conserva 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 iniciales y finales de los valores de campos CSV de forma predeterminada. Los registros que difieren solo por espacios iniciales o finales se vuelven idénticos después del recorte y están sujetos a la misma deduplicación.
• Resolución:
  • Habilita 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, incluidos los 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 planas a planas, establece jitterbit.transformation.disable_normalization en true. Para transformaciones planas 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 tipificado 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á tipificado numéricamente, convierte el valor explícitamente 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 descendentes 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 utilizando 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:
  • Verifica los registros de operaciones para 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 fallo de una 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 útil 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 hexadecimales 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 hexadecimal 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 hexadecimal (85) al byte reportado por StringToHex($readFile) y la cadena de reemplazo (~) según sea necesario, luego asigna el valor desinfectado.

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 la ruta de origen no se puede encontrar

• 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 de operación inesperados 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 que falle 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.
• Posible causa: 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 de bucle. El límite predeterminado es 50,000 iteraciones.
• Posibles causas:
  • 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 recuento de iteraciones combinadas 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.

RunOperation deja de ejecutarse después de 50 llamadas síncronas en un bucle While

• Síntoma: Después de actualizar un agente privado a la versión 12.11 o posterior, un script que llama a RunOperation, RunOperationFromProject, o ReRunOperation de forma síncrona desde dentro de un bucle While procesa menos registros de lo esperado. No ocurre ningún error a nivel de operación a menos que el script mismo verifique el valor de retorno de la función o llame a GetLastError. El registro de operación muestra una entrada que identifica la operación que se invocaba cuando se alcanzó el límite.

• Posible causa: A partir de la versión 12.11 del agente, un límite a nivel de agente (MaxSynchronousRunOperationCallsInLoop en la sección [OperationEngine] del archivo jitterbit.conf, 50 de forma predeterminada) limita el número de llamadas síncronas a RunOperation, RunOperationFromProject y ReRunOperation realizadas desde dentro de un único bucle While; los tres comparten un recuento acumulativo por bucle. Una vez alcanzado el límite, cada llamada posterior devuelve false sin generar un error, por lo que un bucle que no verifica el valor de retorno continúa iterando sin notar que las llamadas posteriores no hicieron nada.

• Resolución:

  • Si el bucle no verifica el valor de retorno, envuelve la llamada para que un límite excedido aparezca como error de script, por ejemplo: If(!RunOperation("<TAG>operation:MyOp</TAG>"), RaiseError(GetLastError()));.
  • Para aumentar el límite de una operación específica, establece la variable Jitterbit jitterbit.operation.max_sync_runop_calls_in_loop antes de que se ejecute el bucle, siempre que se permitan anulaciones por operación (MaxSynchronousRunOperationCallsInLoopOverrideAllowed).
  • Para aumentar el valor predeterminado en todo el agente, incrementa MaxSynchronousRunOperationCallsInLoop en la sección [OperationEngine] del archivo jitterbit.conf.

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 ser omitido.

• Posibles causas:

  • RunScript precede a Unmap en la misma expresión de mapeo (por ejemplo, RunScript("<TAG>script:MyScript</TAG>"); Unmap();). En versiones de agente anteriores a la 12.9, esta combinación no desmapiaba el campo.
  • Unmap se llama 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 desmapieo 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 Unmap se llama 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 con configuraciones de transacción conflictivas.
• Posible causa: Tanto jitterbit.scripting.db.auto_commit como jitterbit.scripting.db.transaction están establecidas 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 establece solo la variable apropiada:
  • Para confirmación automática (cada instrucción confirmada inmediatamente): establece $jitterbit.scripting.db.auto_commit = true y deja jitterbit.scripting.db.transaction sin establecer o en false.
  • Para control de transacciones (confirmación al final de la transformación): establece $jitterbit.scripting.db.transaction = true y jitterbit.scripting.db.auto_commit = false.

CallStoredProcedure: resultSet siempre nulo con controladores ODBC

• Síntoma: Un script que utiliza CallStoredProcedure devuelve null para el parámetro resultSet aunque el procedimiento almacenado devuelva datos.
• Causa posible: El parámetro resultSet solo es compatible con controladores de base de datos JDBC. Cuando el endpoint de base de datos utiliza 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 utilizar un controlador JDBC en lugar de ODBC.
  • Si no es posible cambiar controladores, recupera los datos de salida a través de parámetros de salida en lugar del argumento resultSet.

CallStoredProcedure: "No se pudo encontrar el procedimiento almacenado o la función" 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 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. Determina si el objeto de base de datos que se está llamando es una función de PostgreSQL (devuelve un valor) o un procedimiento (sin valor de retorno).

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

     • Función: utiliza SELECT.

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

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

     • Procedimiento: utiliza 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 endpoint de base de datos utiliza un controlador ODBC.
• Causa posible: DBLoad solo funciona con endpoints de base de datos configurados para utilizar un controlador JDBC. No es compatible con controladores ODBC.
• Resolución: Confirma que el endpoint de base de datos asociado con la actividad de destino utiliza un controlador JDBC. Si utiliza un controlador ODBC, cambia 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, establece 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, reemplaza AESDecryption con AESDecryptionEx, que es compatible con OpenSSL 3 de forma predeterminada en versiones de agente 11.42 o posterior.

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

• Síntoma: Al probar un paso de script o una 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 mediante 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. La resolución de conexión propia de una función es un caso separado que no utiliza el Valor predeterminado en absoluto; consulta Una función falla cuando su campo de conexión de punto final se establece en una variable.
• Resolución:
  • Establece 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 utiliza 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 se establece de otra manera. Consulta Variables de proyecto para obtener detalles de configuración.
  • Usa 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 utiliza. 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 usarla 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 se hace referencia a la variable global en un campo de configuración del conector en lugar de directamente en un script, también debes definir un valor predeterminado por campo para ese campo (consulta Define 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).

Una función falla cuando su campo de conexión de punto final se establece en una variable

• Síntoma: Probar un script (usando Ejecutar prueba) que llama a una función como DBLookup, DBExecute, o SfLookup falla, por ejemplo con:

  No suitable driver found for [...]
  

  o un error que indica un marcador de posición de variable sin resolver en la dirección del punto final. El mismo script se ejecuta correctamente cuando se implementa y ejecuta en una operación.

• Causa posible: La conexión utilizada por la función tiene un campo (como Inicio de sesión, Contraseña, Cadena de conexión, o una dirección de servidor) establecido en una variable global o de proyecto. Probar un script ejecuta solo el script probado, por lo que la variable aún no ha recibido su valor en tiempo de ejecución cuando la función resuelve la conexión. A diferencia de una variable referenciada directamente en un campo configurado de una actividad, esto no se cubre con el Valor predeterminado de una variable; una función como estas no lee el valor predeterminado al resolver una conexión. Para una variable referenciada directamente en un script o mapeo en su lugar, donde un Valor predeterminado sí resuelve el problema, consulta Las variables de proyecto devuelven valores vacíos durante pruebas de scripts y transformaciones.

• Resolución: Antes de la llamada a la función, asigna temporalmente la misma variable global o de proyecto su valor real directamente dentro del script probado (por ejemplo, $login = "value"; para una variable llamada login), luego elimina la asignación antes de desplegar la operación.

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:

  • Usa IfEmpty para manejar tanto valores nulos 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 nulo o una cadena vacía
    result = IfEmpty($myField, "default");
    

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

  • Corrige 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 que se asigne como número en lugar de 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 que es muy 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 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 previene esto: especifica el tipo de datos pero no cambia cómo se almacena o se calcula el valor.

• Resolución:

  • Aplica Round al resultado: Usa Round con el número de decimales requerido 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 afectada.
• Posible causa: Con la versión 12.8 del agente y posteriores, 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 la 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.
• Posible causa: 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:

  • Especifica la expiración en ReadCache: Pasa el número deseado de segundos como parámetro expirationSeconds para preservar o extender la vida útil del valor en caché en cada lectura:

    // Resets expiration to 24 hours on each read
    testVal = ReadCache("CacheTest", 86400, "env");
    

  • Pasa -1 para preservar la expiración de escritura: Pasar un valor no positivo hace que ReadCache retenga 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 "La versión XML debe ser 1.0 o 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"?>.

• Posible causa: 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 al XML de entrada.

• Resolución:

  • Actualizar el XSLT para producir salida XML: Cambiar la declaración de salida de la hoja de estilos a <xsl:output method="xml"/>, o eliminar la declaración xsl:output por completo (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 (obsoleto) 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 hacerlo de forma relativa al nodo actual. Una expresión como "//Item/ItemName" coincide con el primer ItemName en cualquier parte 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 de forma lexicográfica, no cronológica

• 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 cadenas (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, cambiar a un formato que se ordene correctamente cuando se ordena 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, analizar la porción de fecha de cada nombre de archivo en una clave ordenable (por ejemplo, YYYYMMDDHHMMSS) y ordenar 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 que pasa 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 !.
• Posibles causas:
  • URLEncode sigue RFC 1738 y trata estos caracteres como "seguros", por lo que nunca los codifica: $ - _ . + ! * ' ( ) ,. Un destino que espera que estos caracteres estén codificados en 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 +), usa 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 "Falló la llamada a Jitterbit Tomcat"

• 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 estén ejecutándose. El script puede ejecutarse correctamente cuando se reduce su complejidad (por ejemplo, al disminuir 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
  

• Posible causa: JavaScript profundamente recursivo puede exceder el límite de profundidad de recursión del motor JavaScript del agente, produciendo un desbordamiento de pila que se manifiesta 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, usa un enfoque que no dependa de ella.
  • Ten en cuenta que el límite de iteración de bucle por script separado (JavaScriptMaxIterations, consulta Script loop iteration limit exceeded) no aumenta el techo de recursión, que no se expone como una configuración personalizable.

JavaScript: cambios de variables globales perdidos en caso de fallo del 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 correctamente. 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 de tiempo de ejecución impredecible.
• Resolución:
  • Estructura los scripts de JavaScript para que todas las asignaciones de variables globales ocurran después de la lógica que podría fallar, o usa manejo de errores para prevenir fallos a mitad del script.
  • Para cualquier variable dada en un script de JavaScript, usa 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 valores de variables en puntos clave durante la ejecución.

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

• Síntoma: Al llamar a Jitterbit.GetVar en una variable de proyecto definida por el usuario en un paso de script JavaScript, se devuelve null en lugar del valor de la variable, sin mensaje de error.
• Posible causa: Jitterbit.GetVar y Jitterbit.SetVar están diseñados para variables del sistema Jitterbit (por ejemplo, jitterbit.operation.name) y para 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 $nombre 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 se puede leer nuevamente con GetVar dentro del mismo script, pero no persiste en scripts posteriores.

• Resolución: Usa la sintaxis $nombreVariable 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, usa $-prefijo o GetVar/SetVar, no ambos. Consulta también JavaScript: cambios de variable global 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 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 se puede asignar 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 API devuelve:

  507 Insufficient Storage
  

• Posibles causas:

  • El agente o el host de la puerta de enlace se quedó 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 apunta a un problema de registro de dominio privado o configuración de puerta de enlace.

• Resolución:

  • Confirma 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 usa 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, produciendo un 502. Este error es típicamente transitorio y puede no ser reproducible.

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

Errores en tiempo de diseño

Estos problemas aparecen al compilar, validar o implementar 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 de modo 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 en 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 proyecto, 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 utilizaban 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 utiliza. Este reemplazo es en todo el 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 utilizar 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 flujo de trabajo único 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. Utiliza 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 utilizando RunScript.

Errores del sistema y recursos

La fragmentación requiere un conector nativo como origen

• 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 se respeta solo cuando el origen es un conector nativo. Las operaciones que utilizan orígenes nativos como HTTP, Base de datos, Variable y Almacenamiento local 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 del origen original y escribe en una actividad Escribir de Variable.
    • En la segunda operación, lee de una actividad Leer de Variable y escribe en el destino original con fragmentación habilitada. Dado que el conector Variable es nativo, 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 Número máximo de hilos establecido en 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 solo contiene 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 precisión es más importante que el rendimiento por operación, establece Número máximo de hilos 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 Almacenamiento temporal ú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 en aproximadamente 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.