Solución de problemas de operaciones en Jitterbit Studio

Esta guía cubre errores y comportamientos inesperados al crear, implementar y ejecutar operaciones en Jitterbit Studio, incluyendo operaciones, transformaciones, scripts y funciones, así como validación en tiempo de diseño. Si necesitas solucionar 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](#504)
  -   [507 Insufficient Storage](#507)
  -   [502 Bad Gateway](#502)
  

  • Errores en tiempo de diseño

    • Errores comunes de validación de operaciones
    • Errores de reglas 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 del sistema y de recursos

    • La fragmentación requiere un conector nativo como origen
    • Actualizaciones de variables perdidas en operaciones de múltiples subprocesos fragmentadas
    • Error al crear directorio temporal
    • Mensajes de registro de operación truncados en aproximadamente 100 KB
    • El registro de depuración de operaciones expone información de identificación personal y credenciales en texto plano

Pasos de diagnóstico

Estos pasos se aplican a casi cualquier falla de operación y se recomiendan como punto de partida antes de investigar un error específico.

Prueba 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 correcta.

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 organizacional Disable Auto Connector Update esté habilitada).

Verifica los registros de operación

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

Según el tipo de agente, hay datos de registro adicionales disponibles:

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

Aísla 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 de operaciones y programación

Operaciones atrapadas en estado Submitted o Running

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

  Long running operation canceled by System
  

  La cancelación puede ocurrir después de que la operación se ha ejecutado durante 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 bloqueada, incluso cuando la operación se completó en el agente. Esto puede afectar operaciones que normalmente se 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 agota el tiempo.
  • El grupo de agentes está bajo una carga pesada y es lento para recoger o actualizar operaciones en cola.
  • La operación está específicamente atrapada en Submitted: el mensaje de ejecución se puso en cola pero ningún agente en el grupo lo aceptó, porque los agentes están sin conexión, no son 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 el 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 genuinamente de larga duración. Los registros también pueden revelar un error específico a resolver, como 401 Unauthorized (verifica las credenciales) o 429 Too Many Requests. Un 429 de un endpoint de destino se puede mitigar reduciendo la velocidad de solicitud o agregando lógica de reintentos; un 429 de la puerta de enlace de API de 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 de agente más recientes 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 las operaciones no se pueden cancelar, si el problema se repite o si muchas operaciones se ven afectadas a la vez, ponte en contacto con 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 tienen efecto 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 al entorno está desconectado 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 atraso de operaciones de larga duración o un uso sostenido alto de CPU o memoria puede evitar que un grupo de agentes recoja operaciones programadas a tiempo.
• Resolución:
  • Confirma que el proyecto se haya 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 la 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 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, verifica que Jitterbit Scheduler y Jitterbit Scheduler Service se ejecuten en el Administrador de tareas. En Linux y Docker, usa el comando jitterbit status.
  • Reimplementa el proyecto para forzar la resincronización de la programación con el agente.
  • Si las operaciones están atrapadas en un estado Pending, cancélalas desde 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 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 del 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 variable global rellenada 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 tipo de ejecución del Invoke Operation configurado como Asincrónico, 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 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. Para comportamiento equivalente en operaciones multihilo fragmentadas, consulta Variable updates lost in chunked multi-threaded operations.
• 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 tipo de ejecución del Invoke Operation configurado como Sincrónico, 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 variable global.
  • Para compartir datos entre operaciones que deben ejecutarse independientemente, persiste los datos con funciones de caché (WriteCache y ReadCache) en lugar de depender de un diccionario o variable global entre subprocesos. Por defecto, 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) agrega latencia y no garantiza que la operación secundaria haya terminado; en su lugar, ejecuta la operación de forma sincrónica.

Errores de conexión y autenticación

Certificado de Salesforce: discrepancia en 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 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: Este es un problema a nivel de agente con las conexiones de base de datos interna del agente privado. Consulta Errores de conexión TranDb en la guía de solución de problemas del agente para conocer las causas y la resolución.

Error al cargar certificado de cliente en agentes privados de Linux

• Síntoma: Una operación que realiza una llamada de servicio web TLS mutuo (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 exitosamente 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:

  • Verifica que la cuenta que ejecuta el agente de Jitterbit tenga acceso de lectura al archivo de clave privada y a todos los directorios principales.
  • Comprueba si SELinux o AppArmor están 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, el siguiente error aparece en el registro de operación:

  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 Replace los caracteres &, <, >, ' y " dentro de la sección CDATA, incluidos los delimitadores de CDATA (<![CDATA[ ... ]]>), por 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 reporta 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 Get response content in base64 string habilitada: la codificación Base64 amplía 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 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 del agente 12.5 y posteriores, así que actualiza primero el agente 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 del esquema se reemplaza por guiones bajos (_). Al usar procesamiento JSON heredado (el predeterminado para proyectos creados antes de la versión 11.48 de Harmony), esto puede causar que el punto final 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 punto final aún espera el nombre original, puede devolver un error como:

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

• Resolución:

  1. Confirmar que se esté usando un esquema JSON en la actividad afectada. Estos esquemas tienen un nodo raíz denominado json:

     

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

  3. Reconfigurar, implementar y ejecutar 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 esta configuración. Las operaciones y esquemas existentes continúan utilizando el procesamiento JSON heredado. Para evitar inconsistencias dentro de un proyecto, reconfigurar todas las operaciones y esquemas existentes después de habilitar esta configuración.

  Para verificar el nombre del campo que se envía al punto de conexión, revisar el valor jsonPropertyName en los datos de entrada o salida de la actividad con el 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 se devuelve como São LuÃs). Típicamente, 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.
• Causa posible: En las versiones del agente 12.8 y 12.9, la detección automática de codificación de caracteres solo analiza 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 analizada.
• Resolución: Actualizar a la versión del agente 12.10 o posterior, que corrige la detección de codificación.

Esquemas duplicados con grupos de sustitución

• Síntoma: Los esquemas duplicados que usan grupos de sustitución XML no son compatibles. Usar uno resulta en 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, limpiar el esquema duplicado y recrearlo usando 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 de 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.
  

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 añadió 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 las dos desincronizadas. Esto se ha corregido, pero una transformación cuya asignación se importó antes de la corrección aún puede verse afectada.

• Resolución: En la transformación afectada, usa Eliminar todas las asignaciones bajo este nodo en el nodo raíz para quitar 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 espejado 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 espejados pueden comportarse de manera diferente a la esperada. Las asignaciones que utilizaron funciones XML que involucran espacios de nombres (como SelectNodes) pueden ahora ser inválidas.

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

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

• Resolución: A partir de la versión 10.27, importar un proyecto cuyos esquemas XML espejados se crearon antes de 10.25 conserva el prefijo del espacio de nombres original, por lo que el esquema es idéntico a cuando se creó. Para forzar una actualización al prefijo del 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 según corresponda.

  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 puede ignorarse. 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 asignación devuelve un valor de cadena no vacío.
• Posible causa: Cuando la transformación procesa una salida de script, coacciona 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 transfiere.
• 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 asignación puede devolver una cadena no numérica, añade una 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 asignados 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 contengan valores. Este problema ocurre específicamente al usar un esquema de origen plano. No ocurre con esquemas reflejados ni esquemas JSON.
• Posible causa: El modo de transformación de transmisión predeterminado procesa registros de manera incremental, lo que puede causar que los campos asignados no reciban valores cuando se usan con esquemas de origen planos.

• Resolución:

  1. Agregar un paso de script al inicio de la operación que desactive las transformaciones de transmisión estableciendo jitterbit.transformation.auto_streaming en false:

     $jitterbit.transformation.auto_streaming = false;
     

  2. Desplegar y ejecutar nuevamente la operación. Para obtener más contexto sobre la transmisión y el procesamiento de transformaciones, consulta Procesamiento de transformaciones.

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

• Síntoma: Una transformación es inválida o falla al desplegar 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 campo que hacen referencia a dos o más nodos de bucle de origen diferentes. Cada nodo de bucle de destino 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 asignados provienen del mismo nodo de bucle de origen.
  3. Si se necesitan datos de múltiples nodos de origen, preprocesa o combina 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 obtener más detalles sobre patrones de asignación válidos, consulta Validez de asignación 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 plano 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 se mantiene solo 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 elimina espacios en blanco iniciales y finales de los valores de campo 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 omite la normalización y preserva todos los registros incluyendo duplicados.
  • Utiliza 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 antes de 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 antes de la transformación. Esto preserva los 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á tipado implícitamente 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 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.

  • Si el campo de origen también está tipado 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, incluso aunque esos campos estén asignados explícitamente. El sistema destino recibe una carga útil que no incluye los campos omitidos, lo que puede causar errores de validación aguas abajo cuando el destino requiere que los campos estén presentes.
• Causa posible: El procesador de salida JSON omite campos con valores null o 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 final 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 finales (por ejemplo, los servicios SOAP de Workday) lo tratan como inválido y devuelven un error.

• Causa: De forma predeterminada, cuando una asignación a un nodo destino resulta en un valor null 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 null o vacío. Si en su lugar el nodo debe estar presente como un elemento vacío, utiliza las variables Jitterbit destino relacionadas jitterbit.target.xml.include_empty_xml y jitterbit.target.xml.include_nil_attribute, que controlan si se incluyen valores vacíos y null en la salida.

Marca de orden de bytes (BOM) en un archivo de origen se transfiere 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 UTF-8 (BOM), 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 cual 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 configurar 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 operación.
• Causa posible: ArchiveFile y ReadFile tienen comportamiento de fallo suave: si alguna de estas funciones falla, se interrumpe el script actual y se agrega una advertencia al registro de operación, 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 operación para ver mensajes de advertencia cuando una operación se realiza correctamente pero falta la salida de archivo esperada.
  • Si el script debe detenerse ante un fallo de función de archivo, envuelve la llamada en una función Eval y llama explícitamente a RaiseError 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 dañados.
• Causa posible: ReadFile no es confiable con contenido de archivo binario y típicamente solo lee una parte 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 no UTF-8 falla cuando se asigna a una carga XML o JSON UTF-8

• Síntoma: Una transformación que mapea contenido de archivo sin procesar leído con ReadFile (por ejemplo, un archivo EDI sin procesar) en un campo de destino XML o JSON con codificación UTF-8 falla durante la conversión de XML o JSON. Reemplazar el valor mapeado 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 válido en UTF-8 (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 multibyte 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 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 hexadecimal (85) al byte reportado por StringToHex($readFile) y la cadena de reemplazo (~) según sea necesario, luego mapea 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.
• Causa posible: FlushFile y FlushAllFiles (y por extensión ArchiveFile) generan un error si ya existe un archivo con el nombre de destino 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 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.)
• Causa posible: 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 la operación falle.

GetJSONString: Ejecución interrumpida en ruta inválida

• Síntoma: Un script que llama a GetJSONString falla cuando la ruta suministrada 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 se invoca la operación a través de una API, puede aparecer como un Proxy Error [502] engañoso devuelto a la persona que llama a 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 superó el límite de iteraciones del bucle de scripts

• Síntoma: Un script falla con un error indicando que se ha alcanzado el número máximo de iteraciones de bucle. El límite predeterminado es de 50.000 iteraciones.
• Causas posibles:
  • Un bucle en un script de Jitterbit supera el límite de iteraciones de la plataforma.
  • Un script de JavaScript contiene múltiples bucles cuyos recuentos de iteraciones combinados superan 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 puede optimizarse para reducir el número de iteraciones.
  • Para scripts de JavaScript en agentes privados, el límite por script puede aumentarse 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 sincrónicas 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 sincrónica desde dentro de un bucle While procesa menos registros de los esperados. No se produce un 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 invocada por nombre (usando su GUID como alternativa si no se puede resolver el nombre) cuando se alcanzó el límite, y GetLastError devuelve esta misma información de identificación.

• Causa posible: A partir de la versión de agente 12.11, 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 sincrónicas a RunOperation, RunOperationFromProject y ReRunOperation realizadas 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 darse cuenta de 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 activado genere un error de script, por ejemplo: If(!RunOperation("<TAG>operation:MyOp</TAG>"), RaiseError(GetLastError()));.
  • Para aumentar el límite de una operación específica, configura la variable Jitterbit jitterbit.operation.max_sync_runop_calls_in_loop antes de que se ejecute el bucle, siempre que se permitan sobrescrituras 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 genera 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 diferentes tipos, 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 una cadena literal (por ejemplo, $value == "0" o $value == "") en lugar de un número. Si un valor puede llegar como cualquier tipo, convierte ambos operandos al mismo tipo (por ejemplo, con String) antes de comparar.

Unmap no desmapea un campo cuando se utiliza junto con RunScript

• Síntoma: La expresión de mapeo de un campo destino implica 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 12.9, esta combinación no desmaqueaba 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 destino. RunScript devuelve el resultado del script llamado como una cadena en lugar de propagar una señal de desmapeo al 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 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 Unmap fuera del script llamado y al interior de la propia expresión de mapeo del campo 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 utiliza 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 configuradas en true en el script antes de la llamada 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 transacción explícito, y luego configura solo la variable apropiada:
  • Para confirmación automática (cada declaración confirmada inmediatamente): establece $jitterbit.scripting.db.auto_commit = true y deja jitterbit.scripting.db.transaction sin establecer o en false.
  • Para control de transacción (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 usa CallStoredProcedure devuelve null para el parámetro resultSet aunque el procedimiento almacenado devuelve datos.
• Causa posible: 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 sin importar 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 no es posible cambiar de controlador, recupera los 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 usa 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 usando 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 usa la sintaxis SQL correcta para el tipo de objeto:

     • Función: usa SELECT.

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

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

     • Procedimiento: usa CALL.

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

       Los procedimientos de PostgreSQL no devuelven un valor; se puede descartar el valor devuelto de DBExecute.

DBLoad: Requiere un controlador de base de datos JDBC

• Síntoma: Una operación que usa DBLoad falla o no produce salida cuando el endpoint de base de datos usa un controlador ODBC.
• Causa posible: DBLoad solo funciona con endpoints de base de datos configurados para usar 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 usa un controlador JDBC. Si usa un controlador ODBC, cambia a JDBC.

AESDecryption falla con datos encriptados bajo OpenSSL 3

• Síntoma: Una operación que usa AESDecryption falla o devuelve salida garbled al desencriptar datos que fueron encriptados usando OpenSSL 3.
• Causa posible: AESDecryption usa un algoritmo AES heredado por defecto que no es compatible con la encriptación de OpenSSL 3. Cuando los datos encriptados se produjeron con OpenSSL 3, la desencriptación 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 aguas arriba de la llamada AESDecryption para habilitar la compatibilidad con OpenSSL 3.
  • Alternativamente, reemplaza AESDecryption con AESDecryptionEx, que es compatible con OpenSSL 3 por defecto en versiones de agente 11.42 o posterior.

Las variables de proyecto devuelven valores vacíos durante pruebas de script y transformación

• 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).
• Posible causa: 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 un 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 alternativa. 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 endpoint se establece en una variable.
• 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 haya sido establecida 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 alternativa cuando la variable no está configurada. 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 alternativo en tiempo de ejecución. Consulta Variables globales para obtener detalles. Si la variable global se referencia 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 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).

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

• Síntoma: Probar un script (utilizando 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 endpoint. El mismo script se ejecuta correctamente cuando se implementa y ejecuta en una operación.

• Posible causa: 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 está cubierto por 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 script y transformación.

• Resolución: Antes de la llamada de 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 implementar la operación.

IsNull devuelve falso para cadenas vacías de datos de fuente JSON

• Síntoma: IsNull devuelve false para un campo asignado desde una fuente JSON, incluso cuando el campo parece no tener valor. La lógica descendente que depende de la verificación de nulo se comporta inesperadamente 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 confiaban en 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 nulo 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 verificar 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 fuente: Si la fuente JSON debe indicar que no hay valor, actualízala para enviar "field": null u omite completamente el campo en lugar de "field": "".

Comparar una variable de cadena con el número 0 inesperadamente devuelve 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 otras lógicas que verifican cero producen resultados inesperados.
• Causa posible: Cuando Jitterbit Script compara valores de diferentes tipos de datos, intenta convertir ambos operandos a dobles 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 luego se evalúa como 0 == 0, que es true.

• Resolución:

  • Asegúrate de que ambos lados de la comparación utilicen el mismo tipo de dato. 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 incluye literales decimales produce un resultado que es 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 a 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 pueden representarse exactamente en punto flotante binario, por lo que la aritmética sobre 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 dato pero no cambia cómo se almacena o computa 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); // devuelve 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 solo de 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 solo de fecha (2026-01-01), lo que puede interrumpir la lógica posterior que espera el formato más corto. CVTDate no se ve afectada.
• Posible causa: Con los agentes de versión 12.8 y posterior, estas funciones tratan la medianoche (00:00:00) como un valor de hora válido y la preservan en el valor devuelto, de la misma manera que cualquier otra hora. Anteriormente, un valor de exactamente medianoche se truncaba a una cadena solo de fecha, mientras que cualquier otra hora se preservaba correctamente.
• Resolución: Si la lógica posterior requiere un valor solo de 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 restablece la expiración del elemento almacenado 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:

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

  • Pasa -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 de <?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, 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.

• Solución:

  • Actualiza el XSLT para producir salida XML: Cambia la declaración de salida de la hoja de estilos a <xsl:output method="xml"/>, o elimina 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.

  • Usa 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, incluyendo HTML. Consulta Plugins disponibles para obtener detalles de instalación.

SelectSingleNode devuelve el nodo incorrecto cuando se utiliza 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 (que comienza 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 lugar del documento, independientemente del elemento Item que se haya recuperado de la matriz.

• Solución:

  • Usa una ruta relativa: Omite los // iniciales y especifica 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: envuelve 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");
    

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 enviar datos binarios sin procesar. Cuando recibe un valor binario, lo convierte de vuelta a hexadecimal para mostrarlo. El mismo comportamiento se aplica en la ventana de prueba de script. La conversión funciona correctamente; solo la visualización se ve afectada.

• Solución: Para trabajar con o verificar la salida binaria, escríbela 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 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 fecha.
• Solución:
  • Si controlas la convención de nombres de archivo, cambia 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, 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 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, los caracteres multibyte pueden no codificarse como se espera.

• Resolución:

  • Cuando sea necesario codificar caracteres "seguros" (por ejemplo, en una contraseña de OAuth o en 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 "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, incluso aunque los servicios de Jitterbit Apache y Jitterbit Tomcat en el agente estén ejecutándose. El script puede tener éxito 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 de 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 separado por script (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 personalizable.

JavaScript: cambios de variables globales perdidos en 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 se confirman solo 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 en tiempo de ejecución impredecible.
• 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 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 estableciendo, 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: 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.
• Causa posible: Jitterbit.GetVar y Jitterbit.SetVar están destinados a variables del sistema de 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 punto; pasar tal nombre a GetVar devuelve null. En su lugar, referencia esas variables directamente con $nombre. Estas funciones también convierten todos los valores a cadenas, por lo que no son apropiadas para arreglos 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 punto. Reserva GetVar y SetVar para variables del sistema de Jitterbit y para variables cuyos nombres contienen punto (por ejemplo, $hola.mundo), a las 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 en variables globales perdidos en caso de falla del 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 de 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 no se puede asignar la solicitud a un agente disponible. Consulta HTTP 504 Gateway Timeout en la guía de solución de problemas del Administrador de API para las causas completas y la resolución.

507 Insufficient Storage

• Síntoma: Una llamada de 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 suficiente espacio en disco disponible. Esto generalmente apunta a un problema de registro de dominio privado o configuración de la puerta de enlace.

• Resolución:

  • Confirma que el agente o el host de la puerta de enlace tenga 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 existe ese archivo o directorio" para la causa y 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.

• Causa posible: El servicio JBMQ no devolvió una respuesta completa a la solicitud, produciendo un 502. Este error generalmente es transitorio y puede no ser reproducible.

• Resolución:
  1. Reintenta la operación.
  2. Si el error persiste, contacta al 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 lista 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 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 de patrón de archivo de dos destinos donde la actividad HTTP Destino 1 escriba a una segunda actividad 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 del mensaje de error para corregir las operaciones para que sean válidas. Para resolver estos errores, completa los siguientes pasos:

1. Duplica la actividad 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 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.

Deshabilitar la regla de validación HTTP

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

1. Abre la configuración del proyecto:

   

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

   

3. Haz clic en Guardar.

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

Rehabilitar la regla de validación HTTP

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

1. Abre la configuración del proyecto.

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

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

4. Resuelve los errores de validación HTTP (consulta Resuelve los 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 implementadas actualmente. 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 el 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 del 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, usa importación selectiva, que marca conflictos con componentes con el 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 solo para agentes privados. Los agentes en la nube no soportan 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 del conector solo para agentes privados con conectores compatibles con la nube (como HTTP v2 para API REST, o el conector Database 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 la 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 se hace clic en Continuar, el archivo existente se reemplaza en cada ubicación donde se usa. 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 lo referencia más de un componente, Studio muestra un diálogo Esquema utilizado por múltiples componentes listándolos (consulta Actualizar esquemas definidos por transformación). Evalúa el impacto en todos los componentes listados 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 renombra el nuevo archivo antes de cargarlo) para que no sobrescriba el archivo compartido.

La implementación de la plantilla de proceso de Marketplace falla por discrepancia de esquema

• Síntoma: Un proyecto importado de una plantilla de proceso de Marketplace no se implementa o produce errores en tiempo de ejecución porque faltan campos en una transformación o falla la validación de actividades de origen y destino.
• Causa posible: Las plantillas de proceso se desarrollan contra una instancia de endpoint específica. Si tu instancia difiere (por ejemplo, si tu organización de Salesforce o NetSuite tiene campos personalizados o estándar diferentes), es posible que los esquemas insertados en las transformaciones de la plantilla no coincidan con tu endpoint.
• 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 endpoint conectado.
  2. Si el esquema aún no coincide después de actualizar, borra el esquema existente y duplica uno nuevo desde un archivo de muestra actual o directamente desde el endpoint.
  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 ralentiza 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 al guardar 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 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 tener menos operaciones por flujo de trabajo mejora la capacidad de respuesta. Usa acciones de operación para encadenar subflujos de trabajo juntos.
  • Si la lentitud ocurre específicamente al guardar un script grande, divide el script en scripts más pequeños y llámlos usando RunScript.

Errores del sistema y recursos

La segmentación requiere un conector nativo como origen

• Síntoma: Una operación con segmentación habilitada envía todos los registros al destino en un solo lote en lugar de respetar el tamaño de segmento configurado. Los errores del destino indican que se superó el límite de lotes (por ejemplo, Salesforce devuelve EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call).
• Posible causa: La segmentación se respeta solo cuando el origen es un conector nativo. Las operaciones que utilizan orígenes nativos como HTTP, Database, Variable y Local Storage respetan la segmentación normalmente.
• Solución:
  • Si la segmentación no es necesaria, desactívala en las opciones de operación.
  • Si la segmentación es necesaria, divide la operación en dos:
    • En la primera operación, lee del origen original y escribe en una actividad Write de Variable.
    • En la segunda operación, lee de una actividad Read de Variable y escribe en el destino original con segmentación habilitada. Dado que el conector Variable es nativo, la segmentación funciona correctamente en esta operación. Para los pasos de configuración de segmentación, consulta Configurar segmentación de operación.

Actualizaciones de variables perdidas en operaciones multihilo segmentadas

• Síntoma: Cuando una operación se ejecuta con segmentació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 preservan completamente después de que se completa. Un caso posible es rellenar una variable de diccionario o matriz desde cada registro de origen y encontrar 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 las actividades de Salesforce, que tienen un valor predeterminado de 2 hilos.
• Posible causa: 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 con el estado compartido. Solo se preservan los cambios realizados por el primer hilo cuando se completa la operación; los cambios de todos los demás hilos se descartan.
• Solución:
  • Si la corrección es más importante que el rendimiento por operación, establece Max Number of Threads en 1. Cada segmento 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, coloca la salida de cada hilo en un archivo único de Temporary Storage o en una tabla de base de datos de ensayo, luego consolida los resultados en una operación posterior de un solo hilo. Para un ejemplo práctico del patrón de ensayo, consulta Ámbito de variables con segmentación.
  • De manera más general, no confíes en actualizaciones de variables globales o de proyecto de operaciones segmentadas y multihilo en scripts u operaciones posteriores. Si el estado de la variable debe preservarse, establece esas variables en un paso de operación no segmentado que se ejecute antes o después de la transformación segmentada. Para detalles sobre el comportamiento de segmentación con variables, consulta Usar variables con segmentación.

No se pudo crear el directorio temporal

• Síntoma: Una operación no puede crear un directorio temporal y muestra un error como el siguiente:

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

  En un grupo de agentes en la nube, es posible que muestre No space left on device.

• Posibles causas:

  • En un agente privado, la cuenta de servicio del Agente de Jitterbit carece de permisos a nivel del SO en la ruta de archivos temporales, o el disco está lleno.
  • En un grupo de agentes en la nube, la causa está en el lado del agente administrado por Jitterbit, no 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 en el lado del agente que Jitterbit resuelve. Contacta a soporte de Jitterbit e incluye el mensaje de error y la hora en que ocurrieron las fallas.

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

• Síntoma: Un mensaje de 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 de registro de operación que superan 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 generen mensajes de registro más cortos.

El registro de depuración de operación expone información personal (PII) y credenciales en texto plano

• Síntoma: Datos sensibles, credenciales o información de identificación personal (PII) aparecen en los registros de 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 sin cifrar durante 30 días.
• Resolución:
  • Usa 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 deshabilitar 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.